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‘Without a doubts the Premiere Resource Editor 
for the Mac OS ... A wealth of time-saving tools.^^ 
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"A distinct im.provem,ent over Apple's ResEdit." 

— MacTech Magazine 

'Every Mac OS developer should own a copy of Resorcerer ” 

— Leonard Rosenthal, Aladdin Systems 

''Without Resorcerer, our localization efforts would look like a ^ 

Tower of BabeL Don't do product without it!" 

- Greg Galanos, CEO and President, Metrowerks 

“Resorcerer's data template system is amazing." 

- Bill Goodman, author of Smaller Installer and Compact Pro 

“Resorcerer Rocks! Buy it, you will NOT regret it." 

- Joe Zobkiw, author of A Fragment of Your Imagination 

“Resorcerer will pay for itself many times over in saved time and effort." 

- MacUser review 

“The template that disassembles PlCT's is awesome!" A 

- Bill Steinberg, author ofPyro! and PBTools 

“Resorcerer proved indispensible in its own creation!" 

- Doug McKenna, author of Resorcerer 




Version 2.0 



• Very fa^st, HFS browser for viewing file tree of all volumes 
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Most editors DeRez directly to the clipboard 

All graphic editors support screen-copying or partial screen-copying 
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Its own 32-bit List Mgr can open and edit very large data structures 
Templates can pre- and post-process any arbitrary data structure 
Includes nearly 200 templates for common system resources 
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Full integrated support for editing color dialogs and menus 
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Editors for cursors, versions, pictures, bundles, and lots more 
Relied on by thousands of Macintosh developers around the world 


Includes: Electronic documentation 
60-day Money-Back Guarantee 
Domestic standard shipping 


Payment: Check, PC’s, or Visa/MC 
Taxes: Colorado customers only 


Extras (call, fax, or email us): 


JLJAI/Xao UX CXXXCIXX \JLOJ 

COD, FedEx, UPS Blue/Ked, 


International Shipping 


MATHEM^STHETICS, INC. 
PO Box 298 

Boulder, CO 80306-0298 USA 
Phone: (303) 440-0707 
Fax: (303) 440-0504 


resorcerer@mathemaesthetics. com 


To order by credit card^ or to get the latest news, bug fixes, updates, and apprentices, visit our website... 


www.mathemaesthetics.com 
















For Macintosh 
Programmers & Developers 


A publication of XpLAINCORPORATION 


How To Communicate With Us 


In this electronic age, the art of 
communication has become both easier and 
more complicated. Is it any surprise that we 
fjrefer e-mail? 

If you have any questions, feel free to call us 
at 8 O 5 / 49 / 1-9797 or fax us at 805/494-9798. 

If you would like a subscription or need 
customer service, feel free to contact 
Developer Depot Customer Service at 
800-MACDEV-l 


DEPAKIMEIVIS 

E-MaO/URL 

Orders, Circulation, & Customer Service 

cust_sctvicc@mactcch. com 

Press Releases 

press_rele 2 i,ses@mactech .com 

Ad Sales 

ad_sitles@mactech.com 

Editorial 

eclitorial@mactech .com 

Programmer’s Cliallenge 

pn:)g_challenge@mactech .com 

Online Support 

onlinc@mactcch.com 

Accounting 

accx)unting@mactech.com 

Marketing 

mitikeling@ma clecl 1 .corn 

General 

info@ma ctech .com 

Web Site (articles, info, LIRI-s and more...) 

http://wwvv.mactech.com 


MacTech Magazine 

Mac'Iech Magazine is grateful 
to the follounng individuals who 
conlrihule on a regular basis. 
We encourage others to share 
the technology. 

We are dedicated to the 
distribut ion of usef ul 
programming information 
without regard to Apple 's 
developer status. 

For information on submitting 
articles, ask us for our writer’s 
kit which includes the terms 
and conditiom upon which we 
publish articles. 


Editorial Board of Advisors 

Jordan Dea-Mattson, Jim Straus, 
and Jon Wiederspan 


Editorial Staff 

Publisher • Neil Ticktin 

Editor Emeritus • Erie Gundrum 

Editor • Nick “nick.c’' DeMello 

Managing Editor • Jessica Courtney 

Online Editor • Jeff elites 

Web Editors • Kevin Avila, Scott Anchin 

Contributing Editors 

• Jim Black, Apple Computer, Inc. 

• Michael Brian Bentley 

• Tantek Celik, Microsoft Corporation 

• Richard Clark 

• Marshall Clow 

• Carl de Cordova 

• Andrew S. Downs 

• Jim Gochee, Connectix 

• Steve Kiene, Mindvision 

• l^eter N Lewis 

• Rich Morin, PrimeTime F-reeware, Inc. 

• Steve Sisak, Codewcll Corporation 

Regular Columnists 

Getting Started • Dave Mark and Dan Parks Sydow 
Programmer’s Challenge • Bob Boonstra 
From the Factory Floor • Dave Mark, Metrowerks 
Tips & Tidbits • Jeff elites 


Xplain Corporation 
chief Executive Officer • Neil Ticktin 
President • Andrea J. Sniderman 
Controller • Michael Friedman 
Production Manager • Jessica Courtney 
Production • Terrell Dunn 
Advertising Director • Dale Hansman 
Marketing Manager • Nick DeMello 
Events Managers • lohn Churchill, 

Susan M. Worley 

Network Administrator • Chris Barms 
Accounting • Jan Webloer, Marcie Moriarty 
Customer Relations • Molly Covin 

Susan Pomrantz 

Shipping/Receiving • Joel Licardie 

Board of Advisors • Steven Geller, Blake Park, 
and Alan Carsrud 


PRINTED WITH 

SOY INK 


Tliis publication is 
printed on paper with 
recycled content. 


All a)ntents are Copyright 1984-1999 I:>y Xj^lain Corj^oration. All rights reserved. MacTcvh, EX*velo[X‘r De|X)t, and Spixxkel aie registered tradeimiks of X|:)lain Coipomtion. Depot, The Depot, 
Depot,Storey Video I>c‘p()t, MacD(v-l, TI IINK Refemnce, NctProfcssional, NctPmLive, JavaTcch, WebTcxh, RcTcxh, and the MacTiitorMan are Uxidernaiks of Xplain Coiporation. Other irademiirks 
and co})yrights apixaring in tliis piinting or software remain tlie property of tlieir resfxctive holdeis. Xplain Cc;qx)ralion does not iissume any liability for enois or omissions by any of tlie 
advcitisci:s, in advertising content, alitorbl, or other content found herein. Opinions or expressions stated herein are not necc^sjirily those' of the publlslxr and therefore, publisher a.s.sumc?s no 
lialxlity in regards to said statements. 


MacTcch Magazine (ISSN: 1067-8360 / USPS: 010-227.) is published monthly by Xplain Corporation, 850-P Hampshire Road, Westlake Village, CA 
91361-2800. Voice: 805/494-9797, FAX: 805/494-9798. Domestic sul)scriplion rales are $47.00 per year. Canadian subscriptions are $59-00 per year. All 
other international suInscriptions are $97.00 per year. Dome.stic source code disk subscriptions are $77 per year. All international disk sulnscriptions are 
$97.00 a year. iMease remit in U.S. funds only. Periodical postage is paid at Diousand Oaks, CA and at additional mailing office. 

POSTMASTER: Send address changes to MacTech M^aziiie, P.O. Box 5200, Westlake Village, CA 91359-5200. 



The Staff 


MAd’ECH • June 1999 




























C . Q- . It. .. e . n. . t: . s, 

June 1999 • Volume 15, Issue 06 


Normal 



Plane 


3D Graphics Engine Essentials 


page 57 


F EAT V RE Articles 


PROGRAMMIMG TECHMIQIIES 

34 Fast Blit Strategies: 

A Mac Programmer’s Guide 

Getting better video performance out of the 
^ Mac isn’t hard to do — if you follow a few rules 
by Kas Thomas 

GAMES PROGRAMMIMG 

57 3D Graphics Engine Essentials 

A crash course on topics that ever)^ 3D engine 
designer needs to master 
by Eric Umgyel 


POWERPLAMT WORKSHOP 

16 Utility in Utilities 

Kxploring the PowerPlant Utility Classes 
by John C. Daub 

EXPLAIMIT^** 

20 NetB<H)ting and You 

Or, how I learned to stop worrying and love the server 
by Kenneth Stattenfield 


For Madttiosh 
Fro}>rammers & Developers 



Colu m n s 

4 VIEWPOINT 

by Nick DeMello 

GETTliyC STARTED 

6 Resource templates 

by Dan Parks Sydow 

PROGRAMMER'S CHALLENGE 

42 Telraminx 

by Bob Boonstra 

FROM THE FACTORY FLOOR 

53 A Conversation with Chuck Shotton 

hyf Chuck Shotton and Dat v Mark 

56 MACTECH ONLINE 

by MI elites 



TOOLS OF THE TRADE 

24 MacsBug Revisited 

Tliis is not your father’s low-level debugger 
by DanielJalkut 


Reader Resources 

71 Tips & Tidbits 

72 Advertiser & Product Index 


About the cover... 

This month's cover by Terrell Dunn, is a tribute to the great 3D games that have recently come to the Macintosh. Created using MetaCreations 
Infini-D, this cotw illustrates the kind of gaming ive'll be seeing as the Macintosh continues to evolve into the ultimate gaming PC. 


Junk 1999 • MacTf.cii 


lAiiLi: oi- Con TKN'is 


3 






























































VIEWPOINT 


by Nick DeMello 


'rhe convention months are hdckl 

I/ast month was Apple’s World Wide Developer 
Conference, Apple’s chance to talk directly to developers. 
Next month Mac’Iech will be presenting a full conference 
report, bur I’d like to share some of my own perspectives 
on the conference in this months viewpoint. 

WWDC is usually one of the most thrilling 
conventions of the year. Apple presents some exciting 
new directions for the platform, there are dramatic new 
announcements about technologies we’ve never heard of, 
and you get to meet all the new managers, engineers, and 
evangelists. Usually. 

This year tliough, WWDC was kind of boring. 

First off, Steve jobs announced the new system road 
map. Tn 1999, Apple will continue to develop Mac OS X 
and Mac OS 8. A preview release of Mac OS X was 
di.stributed at the show and Apple announc’ccl I hat an 
update to Mac OS 8.6 was available on the web. Basically, 
same game [)lan as last year. 

Then they talked about hardware. FireWire is the new 
standard for high speed data connection, and Apple 
showed off the new blue G3's with FireWire and a new 
FireWire PCMCIA card for PowerBoc:)ks (should be 
available in the next month or two). USB is the .standard 
for desktop connectivity, and the floppy and ADB ix)rl are 
history. AlliVec, the new Vector co-processor in G4 
systems, is the next future of Mac processing. But... that’s 
what they told us last year. 

Introducing my.self to managers, engineers, and 
evangelists, was less than exciting as well. For the mcxst 
part, thc'.se were the same folks I talked to last year — in 
the same departments. We even have the same CFO. 

After the days of Bedrock, OpenDoc, and Khap.sody, 
this years WWDC was downright bc:>ring. 

Not that I miss that kind of excitement. I could get 
used to this kind of boring. 

Despite the lack of ground breaking (and product 
breaking :-) announcements, there was exciting news for 
develc)f)ers. The graphics model for Mac OS X, dubbed 
Quaitz, will be ba.sed on the PDF format, Apple 
announced an incremental update the G3 PowerBook (a 
sleek light weight model with USB), and we’ll be seeing a 
unified printing architec ture for Mac OS 8 and Mac OS X 
(one set of API’s to print from either system). 

Carbon, the subset of ToolBox APIs common to both 



Mac OS 8 and Mac OS X was at the center of many 
sessions. There was as subtle difference in how it was 
presented this year. Last year Carbon was introduced as a 
concept, and the idea was to trim dcown existing 
applic:ations to the Carbon APIs, to allow for easy 
migration to Mac OS X. We were encouraged to develop 
new applications using the ccxuplete Mac OS X APIs. 

Developers responded to this by asking how far back 
the Mac OS X APIs would extend. Would there be libraries, 
or at least stubs, allowing Mac OS X applications to run 
(even in a limited fashion) on Mac OS 8 or even 7.6? 

I think Apple was li.stening. 

This year Carbon was presented less as a migratory 
tc3ol, than as a cross platform optic:)n — a way to create 
new applic:ations for Mac OS X that would be backwards 
compatible to Mac OS 8.1. In one se.ssion, the audience 
was asked how many developers in the audience were 
thinking of creating entirely new applications in Carbon? 

Perhaps the most remarkable change though was in 
the folks who attended the conference. Attendance was 
up a little over previous years, but it wasn’t the same 
crowd of folks we were used to seeing. Apple 
sponsored the attendance of 200 .students, and even 
among the paying crowd there seemed to be an 
unusually large number of first time attendees. A lot of 
these folks were testing the waters of Mac development, 
asking questions about what tools were available for 
Mac developers and how ea.sy it would be to transition 
from windows development to the Mac. 

It’s unceitain at this point how many of these folks 
will take the leap but it’s a good sign that we’re starting to 
see this renewed interest in Mac development. 

Oh, and if you’re looking for that die hard developers 
who were conspicuously absent at WWDC, odds are 
they’re in Mic higan even as you read this. 

I did say the convention months. We start with 
Apple’s side of things at WWDC in May, then June 
brings us MacHack — the gathering of cutting edge Mac 
developers. MacFIack is a week long convention in 
Dearborn Michigan, from June 23-26**L MacHack 
http://www.machack.com/ is where folks gather after 
WWDC to take stock of the current state of Mac 
development, to trade information and touch base with 
each other. Hopefully, I’ll see you there. SJ 
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GETTIlUC 

STARTED 


By Dan Parks Sydow 


Resource Templates 


How a Mac programmer defines custom 
resources to hold program data 

In last month’s Getting Started article we looked at how 
a Mac program works with resources stored in resource files. 
This month we carry on with our look at resources. Rather 
than work with re.sources of the standard types such as WIND, 
MENU, and DLOG, though, we’re now ready to work with 
custom resources of our own design. 

By now you’re very familiar with how a program works 
with standard resources. With a little extra effort your 
program can also work with resources that you define. While 
the predefined resource types suffice for use with program 
interface elements such as windows, menus, and dialog 
boxes, they won’t due if your program wants to store 
application-specific data in a resource. Last month’s Getting 
Started article demonstrated how a program can easily make 
use of resources .stored in an external re.source file. One good 
use of an external resource file is for the storing of 
application data — particularly program preferences. 

Resource Templates 

Graphical re.source editors like Apple’s ResEdit and 
Mathemaesthetics’ Resorcerer depend on templates to make 
resource editing easy. A template displays the value, or 
values, that make up a single resource of a single re.source 
type. For example, you use the MBAR template to edit the 
strings in an MBAR resource. When working with a resource 
editor such as ResEdit, this u.se of templates is invisible. You 
double-click on a resource, and ResEdit uses the template 
a.ssociated with that resource type as the means for 
formatting and displaying the data held in the resource. 
Figure 1 shows a menu bar re.source being edited with the 
u.se of the MBAR template. The template, which is built into 
ResEdit, displays the IDs of the menus that the menu bar 
resource defines to be a part of one menu bar. 



You don’t have to use the buili-in MBAR template when 
viewing an MBAR re.source. If you click on an MBAR resource and 
then ch(X)se Open Using Hex Editor from the Resource menu, you’d 
see the re.source values in a window like the one shown in 
Figure 2. After looking at this window, though, you’ll .see that the 
u.se of a template makes viewing a resource’s data much clearer. 


□ ^MSARIDs 128fromTestApp.r$rcS 

m 

000000 0003 0080 0081 0082 

A. 

000008 


000010 


000018 


000020 


000028 


000030 


000038 


000040 


000048 


000050 


000058 

- 

000060 

■w ■■ 

000068 



Figure 2, Viewing an MBAR resource without the 
use of the MBAR template. 
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RcsEdit supplies templates for dozens of the commonly 
used resource types, including the ALRT, DITL, and DLOG, 
MBAR, and MENU resources. For most of your programming 
nec?ds, iliese built-in templates are all that you’ll ever need. If 
you want to store your own data structures in a resource file, 
however, you’ll want to create your own remf)late so that you 
can view and edit your data in a simple fashion. You’ll also want 
to create your own data-holding resources — the resources that 
ResEdit will formal with the new template. Fortunalely, ResEdit 
makes it easy to add your own template and custom resources 
to a resource file. On the following pages we’ll create both a 
template and a custom resource. And to save a lilile work, the 
template and resource we create will be the same ones we’ll use 
in ill is month’s example program. 

Crlaung a Resourcf Templati* 

Using ResEdit, a new resource of any type is created by 
ch(X)sing Create New Resource from the Resource menu. In tlie 
dialog that appears you see the standard re.sourcr types named 
in a list. A template is itself a resource — a resource of the type 
TMPL. Double-click on TMPL in the list and ResEdit creates a 
new, empty template — as shown in Figure 3. 


name should be four characters, but that Apple reserves type 
names that appear in all lowercase. So make sure to include at 
least one uppercase character in your template’s name. 


IMlsfrom RsrcTemplatejrsrc 


jD Size Name 

120 0 


L □ Info for TMPL 128 from RsrcTemplate.rsrc @ 


Type: 

TMPL 

Size: 0 

ID: 

128 


Name: 

TSTD 


Owner type 


DRVR 

.A. 

WDEF 

1 

MDEF 

■V; 


Attributes: 

□ System Heap □ Locked □ Preload 

□ Purgeable □ Protected □ Compressed 



Figure 4. Giving the neu^ template a name. 

After closing the Info window, it’s time to edit the 
template. 'I’he template will have an item for each data 
element that will be in a (yet-to-be-created) TSTD resource. 
Of course if you choose to give your template a different 
name, then your template won’t be used to formal TSTD 
resources. Rather, it will be used to format resources of the 
type you specify. 

A template item provides a label for the data element and 
specifies the type of data that the element is. Imagine that our 
TSTD re.source will hold just a single data element, and that this 
data element will be a two-byte number. In C, such a number 
could be represented by a short variable. In the template, there 
should be a single item that corresponds to this one data 
element. Figure 5 shows what this item would look like. 


The template resource itself won’t be used by your 
application. Instead, it serves as nothing more than a tool to tell 
ResEdit how to display data of a particular type in ResEdit. 'Ehat 
means you need to specify which resource type the new 
template is to affect. Do this by clicking on the lemt^latc’s ID in 
the TMPL window of the resource file, and then choosing Get 
Resource Info from the Resource menu. In the dialog box that 
opens, type in the name of the resource type that the template 
should format. At this time you’ll need to think of a name for 
the data-holding resources you’ll soon be creating. That is, 
you’re creating a format-defining template resource now, and 
you’ll be creating the actual data-holding custom resource (or 
resources) later. In Figure 4 you see that for our example the 
new template is named TSTD, for “TeST Data.” When you 
choo.se to define a new resource type, keep in mind that the 


£3 TMPL “TSTD“ ID s i28firofri RsrcTempIdtexsrt 

m 

*>(<«««(< 



Label 

write 


Type 

DWRD 


2) 




Figure 5. A template resource that defines one data field. 


A template item can have any label, but the label should be 
somewhat descriptive of what the data element is or what it will 
be used for. The label write was .selected because in the program 
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code this value will be used as a flag to determine whether the 
program should write to a window. The item has to have a type, 
and it must be one of the types that ResEdit recognizes. ResEdit 
doesn’t recognize C, or Pascal, or any other standard 
programming language. Instead, it has it’s own simple set of data 
types. Eor a two-byte value, ResEdit defines the DWRD type. 
DWRD stands for decimal word. The most commonly used 
ResEdit types are: 

DWRD 2-byte word decimal field (maximum value of 32,767) 
DLNG 4-byte long word decimal field (maximum value of 
2,147,483,647) 

PSTR Pascal string field (though no leading “\p” is required) 
CHAR 1-byie character field 

RECT Rectangle field, displaying four coordinate liolding edit 
boxes (i; L, H, R) 

A template can of course hold more than one item — but 
for this introduction we’ll slop at one item so that we can run a 
test that proves the template works. Then we’ll go back and add 
a couple of more items to this .same template. 

Creating a Cusiom Resource. 

To create a cusiom resource — one of a type noi defined by 
ResEdit — choose Create New Resource from the Resource menu. 
You’re creating a resource of your own resource type, so don’t 
look for the type in the list in the Select New Type dialog box. 
Instead, type in the edit box the four characters that make up the 
custom type. 'Phis resource lyjx* should match the template type 
you defined crarlier. For our example, that would be TSTD. Click 
the OK button and a new TSTD resource appc^irs. As shown in 
Figure 6, the resource will lx.* formatted using the TSTD template 
(comf)are the TSTD resource in Figure 6 with the TSTD template 
resource shown back in Figure 5). 


O ^=r~r=^ TMPL “TSTD” ID = 128 from RsrcTemplatej'src g 





Label 

write 

Type 

DWRD 






Figure 6. A custom 757D resource ciLsplayeci 
usirif* the TSTD template. 

Now that we’re satisfied that we can create data-holding 
resources that will be easily viewable and editable with our own 
template, it’s time to go back to the template resource and add 
a couple of more items to it. Open the resource file’s one TMPL 
resource, click on the area where a second item is to be added 
(the “2) *****” string), and ch(K)se Insert New Field(s) from the 


Resource menu. 'Fype in a label and a type. Repeat for each item 
that is to appear in the template. As shown in Figure 7, for our 
TSTD template we’ll have three fields: a 2-byte number, a 4-byte 
number, and a string. 


TMls from RsrtTemplatersrc 


JD Size Name 

120 29 “TSTD” 


□ TMPL “TSTD” IDs 128from RsrcTemplatexsrc 


««««>(( 


Label 

write 

Type 

DWRD 


2^ **^^*^l^ 



Label 

score 

Type 

DLNG 


3) 



Label 

name 

Type 

PSTR 





Figure 7. Ihe JSTD template with three items. 

Our example program will evenmally use the data that’s 
held in one TSTD re.source. The j^rogram will look at the value 
of the write item to .see if the other TSTD resource data should be 
written to a window. A write value of 0 means no, a write value 
of 1 means yes. Fhe score item will hold a high score (wee’ll 
assume we’re writing a game), and the name item will hold the 
name of the person who holds the high score. The details of how 
the program accesses this data become evident just ahead. 

Next, open the one existing TSTD resource. Because the 
template this resource uses has been altered (we’ve added two 
items), you’ll see an aleit that warns you that items are being 
added to the TSTD resource. After dismissing the alert you’ll see 
that the TSTD resource now has edit boxes for entering values for 
the three items. In Figure 8 you see values entered in each item. 


TSTftstrom RsrcTemplatersrc 

IQ;. Size Name 

120 18 



^TSTD IDs 128from RsrcTemplate.rsrc^^^^s 

m 

write 


1 




score 


150800 



name 


Dan P Sydow 







^ ■ 


Figure 8. A ISTD resource with three items. 
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ISPs to offer ndfive routing of AppleTalk, 
(PX and DFCnet between customers' 
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more than a decade. So your business'. 
Internet traffic doesn't queue up behind 
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Now lets see how our TSTD resource would Ik' viewed in 
RcsEdii if there umn V a corresponding TSTD template. Figure 9 
shows the TSTD resource pictured in Figure 8 — but here it's 
opened using KesEdit’s hex editor. The same data is f)resent, it's 
just not formatted in a manner that’s easy to view and easy to edit. 


I TSTD IDs 128from Rsreteiii^iatejrsrc j 


000000 

000008 

000010 

000018 

000020 

000028 

000030 

000038 

000040 

000048 

000050 

000058 

000060 

000068 


3131 3530 3830 3044 1150800D 
616E 2050 2053 7964 an P Syd 
6F77 o«i 




Figure 9. A TSTD resource eieiied uiihout the aid of a template. 


For any given re.source type, you only need to create one 
template re.sourc:e. Now that our TMPL resource of type TSTD is 
completed, any newly created TSTD resource will use it. To 
verify that, choose Create New Resource from ihe Resource 
menu, type in TSTD as the resource type, and click the OK 
britton. Figure 10 shows that ResEdit creates a new empty 
resource and displays it with the help of the TSTD template. 


TSTDsflxjm RsrcTemplcitej*src 


120 

129 


10 

0 


I TSTD IDs 129 from RsrcTemplate.rsrc I 


wri te 
score 
name 




Figure 10, A new TSTD resoiirce automatically 
uses the TSTD template. 


Using Custom Resource Data in an Application 

when a Mac application makes a call to GetNewWindow(), 
information from a WIND resource is loaded into a 
WindowRecord data .structure. The program is then provided with 
a pointer to this structure: 

WindowPtrwind; 

wind = GetNewWindow( 128, nil, (WindowPtr)-IL ); 


Your program can use the WindowPtr variable to obtain 
information stored in the WindowRecord. Tliat’s po.ssible because 
the WindowRecord data type is defined in the universal header 
files and is known to the Toollxix. 

When you want an application that you’re writing to access 
information from a resource ty|ie that vow’ll"defined, youTl have 
to supply the application with the format in which the data is 
stored. Just as a program needs to recognize a WindowRecord 
data stnjcture before it can work with the data from a WIND 
resource, your application needs to have a data structure defined 
for any programmer-defined resource type. 

Consider our own TSTD resource. Any resource of that type 
contains values that correspond to a C language short, long, and 
Str255 — in that order. That means an application that is to u.se 
a TSTD resource needs to define a dara structure that matches 
this format. Here’s that stnjcture: 

typedef struct 
I 

short write; 

long score; 

Str255 name; 

1 TemplateRecord, *TemplatePtr, **TemplateHandle; 


While w'eVe given each field a name thal corresponds 
exactly to the label of a TSTD re.source item, that naming scheme 
isn’t a requirement. As long as I he data .structure consists of 
fields that are of data types that match the re.source item data 
types, the structure is valid. 

Now, when the application needs to access information 
from a TSTD re.source, it makes a call to the Toolbox routine 
Getl ResourceO to load the resource data into memory and to 
return a handle to the data. 

Handle dataHandle: 

dataHandle = GetlResource( ‘TSTD*, 128 ); 

Get1 ResourceO can lx- u.sed to load into memory one 
re.source of any type. The first parameter is the re.source type, 
and the .second is the ID of the paiticular re.source to load. 

Once the TSTD re.source data is loaded into memory, it can 
be acce.s.sed by the application — but not until the application 
is (old the format of the data. Until then, the data appears as ju.st 
a stream of information in memory. Typecasting the generic 
dataHandle variable to a TemplateHandle is the way to tell the 
application how the data is formatted. To gain access to one 
piece of data, the TemplateHandle Is dereferenced twice. Here’s 
how a short variable would lx a.ssigned the value of the first 
item in the TSTD resource. 

Handle dataHandle; 
short resValue; 

dataHandle = GetlResourcc( ‘TSTD*, 128 ); 
resValuc = (** (TemplateHandle)dataHandle).write; 
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After the above code executes, the resValue variable can l')e 
used, and the first menil)cr of the TSTD data in memory can be 
ignored. Tliis applies to eacli of the three TSTD data meml:>ers: 
once variables are assigned the values held in the resource, you 
don’t have to use the handle to the resource data. The following 
snipjXT loads the TSTD data into memorv', then uses assignment 
statements to extract all of the data from that resource. After the 
snippet executes, the variables resValuel, resValue2, and 
resValueS hold the data that is in the resource. 

Handle. dat.aHandle; 
short rcsValucl : 

long tesValLie2: 

Str255 resVaiuel; 

StringPtrsourceStr: 

Size bytes; 

dataHandle = GetlRe.source( ‘TSTD’, 128 ); 

rcsValucl “ (**(TcmplaLcHandlc)dataHandlc).write: 
resValue2 = (* * (Teraplatellandle)datallandle) .score; 
sourceStr = (**(TempiateHandle)dataHandle).name: 
bytes - (**(T€raplateHandle)dataHandle).namelOj + 1; 
BlockMoveData( sourceStr. resValuel. bytes h 

After obtaining a handle, each of the first two assignments 
are straightforward: cast the handle, then dereference it twice to 
access a struct memlxr. Assigning a value to the Str255 variable 
requires a little extra work. A string variable is an array of 
characters, and in C a simple assignment statement can’t be 
made in order to assign the value of one airay to another array. 
'I’hus an assignment like this next one will result in an error 
during compilation: 

rcsValucl - (**(TcmplaicHandlc)daLaHandlc).name; 

Instead of a direct assignment to a Str255 variable, first 
make the assignment to a pointer: 

StringPtr .sourceStr; 

sourccSlr = (**(TemplalcHandlc)dataHandle).name; 


Next, get the length of the string — it can be found in the 
first element of the array that holds the siring. Add one byte to 
account for this first length byte. Then use the Toollxx routine 
BlockMoveDataO to copy the the values in the proper numlier of 
bytes of memory to the Str255 variable. 

SLr2!)3 resValuc'i; 

StringPtr sourceStr; 

Size bytes: 

sourceStr = (**(TemplateHandle)dataHandle).name; 
bytes = (**(TemplateHandle)dataHandle).name[0] t 1; 
BlockMoveData{ sourceStr, re.sValuel, bytes ); 

Once a jirogram has the resource data stored in a variable, 
the information can be used just as data in any variable is u.sed. 
For in.srance, this next snippet adds the short and long values 
together and .stores the result back into the long variable. The 
snippet al.so draws to a window the string held in resValueS. 

resValue2 += resValuel: 

MoveToC 20. 60 ); 
r)rawSLring( rcsValucl ): 



Fast Mac ISAM Access 


*^da«abase 

performaQO? 

ISAI^ 

beats... •=» 

performanoa 


Real-world dala managemenl 
solutions iire typically more complex 
when one examines the pieces, 
than initially recognized by the 
majority of database programmers. 
All softwaie projects aie complex 
puzzles comprised of many details, 
most of which are data-related. Often 
Uxlay’s “DBMS” solutions .sacrifice 
the speed or control essential for a 
competitive application. 

c-tree Plu.s®, by FairCom, has 
been the choice of commercial 
developers for twenty years precisely 
bccau.se it offers the flexibility and 
conu-ol at the detail level to fit a 


wide variety of dala managemenl 
needs. Proven on large Unix servers 
and workstations, c-tree Plus’s 
small footprint and exceptional 
performance have also made it the 
engine of choice for professional 
developers on Mac and Windows, 
c-tree Plus offers sophisticated 
ISAM level control with which the 
developer may define precise data 
management solutions, making it a 
perfect fit for any development 
project requiring .specific data 
handling features. 


C-t:Pee offers the most: 

mature ISAM solution today... 


FairCom’s 
c-tree Plus 
database engine: 

• Advanced Indexing Technology 

• Complete Source Code 

• Complete Transaction Processing 

• ODBC Interface from 
Windows clients 

• Over 25 Developer’s 
Servers Included 

• Royalty Free 

• Standalone, Multi-user or 
Client/server Models 

• Y2K Compliant 

• Supports Metrowerks, 

Symantec Compilers 



The FairCom 
Server: 

A solid, high performance 
database .server that is scalable, 
portable and offers unequalled 
control. FairC’om has been providing 
database solutions to the commercial 
development community for twenty 
years and supporting Mac for nearly 
as long. You won’t find a better Mac 
DBMS .solution, with these features 
and performance anywhere else! 

• Client Side Source Code 

• File Encryption 

• File Mirroring Logic 

• Full Conditional Index Support 

• Full Heterogeneous Networking 

• Multiple Communication Protocols: 
ADSP; SPX; TCP/IP 

• Online Data Backup 

• Small Memory Footprint 

• Flexible OEM Licensing Option.s 

• Source Code Availability 


! pi 
sea i 


supported in one package: 

Mac, MIPS ABI, DEC Alpha, Sun SPARC, Windows 9X, 
SCO, 880PEN, AIX, RS/6000, HP9000, Sun OS, 
Interactive Unix, Linux (Alpha...), AT&T System V, 
QNX, Free BSD, OS/2, Windows NT. Windows 3.1, 
DOS, Netware NLM, & Banyan VINES. 




Phone: USA 573.445.6833 
JAPAN ^1.59.229. 

Qtliwr (aHTH)Hiiy. pnxlurt. wriri ope.i’HtitKj plnlfmtn twmHK urn 


11.3872.9802 

fKSjlHUlitfB UWHtilti 


Junk 1999 • MAcfFBCH 

















RsrcTempiate 

This month’s program is named RsrcTempiate. Running 
RsrcTempiate results in the appearance of the window shown 
in Figure 11. The RsrcTempiate program doesn’t have a 
menu bar — just click the mouse button to close the window 
and quit the program. 




..J .V.; PtCW WlliaOW 


150800 

Dan P Sydow 



Figure 11. The RsrcTempiate window. 


I’he Rsrclemplate program does nothing more than prove 
that the program is successfully accessing the information stored 
in a custom resource. The number 150800 and the string Dan P 
Sydow are both stored in the same custom resource. While the 
very simple RsrcTempiate program may not seem to be doing 
much, it is in lact doing just enough. By displaying a little 
information in a window, we know that the work that went into 
creating a custom resource was successful. 


Creating hie RsrcTemplate Resources 

The project begins with the creation of a new folder named 
RsrcTempiate in your CodeWarrior development folder. Start 
RcsEdit, then create a new resource file named RsrcTempiate.rsre. 
Make sure to designate the RsrcTempiate folder as the resource 
file’s destination, 'fhe resource file will hold just three resources: 
a WIND, a TMPL, and a resource of a custom type — a TSTD. 

The one WIND resource is used for a window that 
displays some of the data from the custom TSTD resource. 
There will be only two lines of information written in the 
window (a number and a string), so the exact placement and 
size of the window isn’t important. 

If you’ve followed along with the preceding walkthough of 
the creation of TMPL and TSTD resources, you already have the 
template and custom resource created. If you have these 
resources saved in a file, copy and paste them into the 
RsrcTempiate.rsrc file. If you haven’t created them, go back and 
read again the discussion on templates and custom resources. 
When you’ve finished, your TMPL and TSTD resources should 
look like the one’s pictured in Figure 12. 


HsTdeinpiatejim 




TMPi'-TSTD” iOs !2»ft^mRsrcTempl<rte.rsrc 


1 ) 

Label 


Type |dWRD | 


2) 

Label 

Type 

3) 
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Type 


DLfJG 


PSTR 


IDs 128 from lhfrcTemplatfi.rsrc W'S 


vwnte 

score 

name 


15080C 


Dan P Sydow 


Figure 12. The TMPL and TSTD resources. 


Creating the RsrcTemplate Project 

Launch CodeWarrior and choose New Project from the File 
menu. Use the MacOS:C_C++:MacOSToolbox:MacOS Toolbox Multi- 
Target project stationary for the new project. Uncheck the Create 
Folder check box before clicking the OK button. Name the 
project RsrcTemplate.mep, and make sure the project’s destination 
is the RsrcTemplate folder. 

Add the RsrcTemplate.rsrc file to the new project, then 
remove the SillyBalls.rsrc file. I'he project doesn’t make use of 
any standard ANSI libraries, so feel free to remove the ANSI 
Libraries folder from the project window. 

Now choose New from the File menu to create a new, empty 
source code window. Save the new window, giving it the name 
RsrcTemplate.c. Choose Add Window from the Project menu to 
add this file to the project. Now remove the SillyBalls.c 
placeholder file from the project window. You’re all set to type 
in the source code. 

If you want to save the work of typing in source code and 
creating resources, you can skip all the above steps and instead 
download the entire RsrcTemplate project folder from 
MacTech’s ftp site at <ftp://ftp.mactech.com/src/>. 

Walking Thr()U(;h the Source Code 

BecaLuse the RsrcTemplate program doesn’t have menus, and 
doesn’t include event handling (the program quits when the 
mouse button is clicked), we’ve got less code than usual to cover. 

The program listing begins with a few constant definitions 
— all of which are resource-related. kWINDResID is the ID of the 
WIND resource, kTSTDResID is the ID of the custom TSTD 
resource, and kResTypeTSTD is the constant that defines the four 
characters that make up the type of our custom resource. 

constants ******^^****^^******y 

//define kWTNDResin I ?.8 

//define kTSTDResID 128 

//define kResTypeTSTD ‘TSTD' 


In order to let the program know the format of our custom 
TSTD resource, we need to define a data stiiicture that includes 
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fields that match the order and data type of cacli item in the 
TSTD resource. If you alter the TSTD resource (and the 
corresponding template), you’ll need to also alter the struct such 
that its fields remain in correlation with the resource items. 

data struciurcs 
lypodef struct 

I 

short write; 

long score; 

Str255 name: 

} TemplateRecord. *TempiatePtr. *‘TemplateHandlo; 

RsrcTemplale declares three global variables. I’he Boolean flag 
gWriteScoreInto tells the program whether it should write lo a 
window the high score and name information that’s stored in tlie 
TSTD re.sourc(?. Tlie gHighScore variable will hold the value from the 
score item in tlie TSTD resource, while the gName variable will hold 
the string from the name item in the .same TSTD resource. 

global varial)lcs 

Boolean gWriteScoreInfo - false: 

long gHighScore; 

Str255 gName; 

Next come the program’s function prototypes, 
fuiiciions 

void ToolRoxInit.( void ); 

void GctTomplateRnrcValuest void ): 

void WriteValut'sToWindow( void ); 


Tlie mainQ function begins by initializing tlie T(x)llx)x and 
opening a window. A call to the application-defined 
GetTemplateRsrcValues() extiacts the data from a TSTD re.soiirce. 
Tliat function stores the value of the first item in the TSTD resource 
(the write item) in the program’s glolral variable gWriteScoreInfo. Tlie 
main() function checks tlie value of gWriteScoreInfo to determine if' 
tlie remaining TSTD data should lie written to the window. If writing 
should take place, we delegate that work to the application-defined 
function WriteValuesToWindow(). Aftei' that the program simply waits 
for ButtonO to reairn a value of true, indicating that the u.ser clicked 
the mouse button. At that time main(), and the program, ends. 

*******«**»***i(i*****i»***^ 

void main( void ) 

( 

Wi iiduwPl. r window; 

ToolBoxlnit{); 

window - GetNewWindowC kWlNDResID, nil, (WindowPtr)-IL ); 
SetPort( window ): 

GatTemplateRsrcValuesO : 

if { gWriteScoreInfo = true ) 

WriteValuesToWindowO ; 

while ( !ButtonO ) 

) 

ToolBoxInitO needs no discussion — it’s the same as prior 
versions. 


YOU 
IC; P D' tE 
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**^***************/ 

void ToolBoxlnit( void ) 

I 

InitGraf( &qd.thePort ); 
InitFonts 0; 

InitWindovsO ; 

InitMenusO ; 

TEInitO ; 

TnitDialogs( nil ); 

InilCursorO ; 


GetTemplateRsrcValuesO l)cgins by calling Get1 Resource() 
to load the data from the TSTD resource to memory and to 
provide the program with a handle to that block of memory. 

/*•**•*•***•*••* GctTcmplalcRsivValucs *^»*****»***/ 

void CetTemplateRsrcValuGsC void ) 

I 

short write; 

Handle dataHandlc; 

StringPtrsourceSlr; 

Size bytes; 

daiallandle = GetlResource( kResTypeTSTD, kTSTDResID ); 

GetTemplateRsrcValuesO continues by extracting the 
individual values from the block of memory that holds all of tlie 
resource information. The generic handle that references the 
memory block is first typecast to a TemplateHandle, then ihe write 
field of the Template Record staicmre is accessed. The value of this 
field is f)laced in the local variable write, and the global variable 
gWriteScoreInfo is then .set according to the value of write. 

write “ (** (TemplateHan(lle)dataHandle) .write; 

if ( write = 0 ) 

gWritcScoreInfo = false; 

olso 

gWriteScoreInfo = true; 

The second item in the TemplateRecord is now extracted, and 
the result is stored in the global variable gHighScore. 

gHighScore * (**(TemplateHandleldataHandle).score; 

Now the third and last item in the TemplateRecord is 
extracted. A local StringPtr variable is first set to point to the 
name field of the TemplateRecord. The number of bytes in the 
string are then determined. Finally, that number of bytes are 
moved into the global variable gName. Recall that a Str255 
variable cannot be assigned a string directly (except upon 
initialization), so this roundabout copying of bytes is necessary. 

sourceStr = (** (TemplateHandlGldaLallaiidle) .name; 

bytes = (**(TcmplatcHandle)datallandle).namelOj + 1; 

BlockMovcDala( sourceStr, gName, bytes ): 

} 

After GetTemplateRsrcValuesO executes, the gHighScore variable 
holds the value that initially c'ame from the score item in the TSTD 
resource, and the gName variable holds ilie .string that initbilly aime 
from the name item in that same resource. vSo at tliis point the 
program lias .stored in its own variables the data it needs — and tJie 
TSTD resource and the TemplateRecord are no longer of interest. 'Ihe 
WriteValuesToWindowO function is called from main() to write the 


infomiation from tliese variables to the program’s window. 
NumToStringO converts tlie value held in tlie long variable gHighScore 
to a siring, and DrawString() writes the resulting string to tlie 
window. Variable gName alrc*ady holds a string, so that variable is 
passed directly to DrawStiingO to write tlie name to the window. 

Z***^**^’WrilcValuesToWindow 

void WriteValue55ToWlndow( void ) 

I 

Str?.55 LempStr; 

MoveTo( 20, 20 ); 

NumToStririg( gHighScore, tempStr ): 

DrawStringl tempStr ); 

MoveTo( 20, 40 ); 

Drawstring( gName ); 

1 


Running RsrcTf.mpiate 

Run RsrcTcmplate by selecting Run from CcxleWarrior’s Project 
menu. After compiling the code and building a program, 
QxleWarrior nins the program. No menu bar apjx^ars — just a 
window. If die TSTD resource was properly read into memory, and 
if die program accessed the values rn)m memory, die program’s one 
window will display two strings — as shown back in Figure 11. 
When you’re sati.sfied that the displayed infomiation Is coirect, click 
the mou.se button to end the program. 

You can have die window disjilay different infomiation by 
editing the TSTD resource. Run ResKdit and open the 
RsrcTemplate.rsrc file and open die fik‘s one TSTD resource. Change 
the value of the score item and the .string in the name item. Note that 
if you change die write item value to 0, the program won’t display 
anything in the window, as expecled. Now save and close the 
re.source file. Open die RsrcTemplate.mcp project and build a new 
version of the RsrcTemplate program. Running die program will 
then result in the display of the new TSTD values. 

Till Next Moniii... 

The template item data types that were descrilxxl in this article 
— DWRD, DLNG, PSTR, CHAR. RECT — may lie all you’ll need in 
order to create your own template. But diere are several other types 
ResEdit defines. While Apples own Reslulit Reference hook Is dated, 
it does hold more than a little information that’s of irse to 
programmeis. For template creation, you’ll lx‘ interested in the list of 
data tyiies for template items — it’s found in Chapter 5: ResIkUt 
Templates. You can freely download a PDF version of the book at 
<http://developer.apple.com/techpubs/mac/resedit/resedit-2.html>. 

From last month’s article you know alxiut resource files — 
including working with multiple re.source files. Now, after reading 
this mondi’s ardcle, you know how to .store program data in a 
custom resource. Next month we’ll tie things togedier to develop a 
program that creates a new resource file, cre<Ues a new custom 
resource in dial file, and then writes prognim information to that 
resource. The progi*am will do all of the.se fc'als “on-die-dy’* (that Is, 
as it executes). 'Ihe program will also Ixf able to subsequently open 
die resource file, access the re.source information, and make use of 
it. If you haven’t already gue.sscxJ, what we’re talking about is die 
prexess of working with a preferences file. qq 
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POWERPLANT 

WORKSHOP 


By John C. Daub, Austin, Texas USA 


Utility in UtiUties 


Exploring the PowerPlant 
Utility Classes 


In The Details 

When you first learn PowerPlant, 
you must concern yourself with the 
larger notions of I’he Framework — the 
event handler, the view hierarchy, the 
Commander chain, Broadcasters and 
Listeners. These are core, foundational 
aspects of PowerPlant that you must 
know and understand to begin writing 
applications in PowerPlant. After you 
have the core down and have hacked 
out your first PowerPlant app, you start 
to explore new areas of The 
Framework: perhaps the Networking 
Classes, Internet Classes, Threads, 
AppleScript-ability. Those areas are 
certainly all good, however Td like to 
suggest one group of classes and code 
that you might not liave thought to take 
a further look at. All the little classes 
that exist in both cohesive groups and 
scattered one-shots throughout The 
Framework — Utility Classes. 

Utility Classes are an important part 
of any framework. They help you 
accomplish the work you need to do by 
perhaps simplifying an API, or providing 
means to manage other objects and 
states, or maybe just consolidate a lot of 
(perhaps commonly used) code into a 
single function call. Utilities won’t solve 
all of your programming problems, but 


they certainly should prove to find a useful place in your 
toolbox as they alleviate a lot of the headaches you encounter 
on a daily basis. Working the use of such utilities into your 
coding habits can help you write more robust and less-error- 
prone code from the onset. 

General Framework Utilities 

Most of the Utility Classes in PowerPlant can be classified 
into a cotiple groups, with a few left over. We’ll take a brief look 
at them all. By the way, you can follow along in source code by 
opening your Utility Classes folder and reading each source file 
as we get to it. 


Core 

1‘here are some Utility Classes that implement the internal 
support structure for portions of The Framework’s functionality. 
UReanimator and URegistrar are two such core classes, as they 
are central to the PPob mechanism. These classes implement 
the ability to instantiate your PPob at runtime. UReanimator 
reads the ‘PPob’ DataStream and calls the proper object 
constructor/creation-routine — found by a table lookup to 
URegistrar — to reanimate your PPob (Window, Dialog, etc.). 
UDebugging and UException are another file combination, 
implementing the core debugging and exception handling 
infrastructure for PowerPlant. UCursor implements basic cursor 
handling. UEnvironrnent collects, maintains, and provides a 
query mechanism on particular environmental information 
(EnvironmentFeature), such as if a certain technology is present 
(Drag and Drop, Thread Manager, Appearance Manager, etc.). 
These core classes are used throughout PowerPlant by the 
framework itself, and of course you are free to use them. In 
fact, you should use the.se facilities provided by The Framework 
becau.se if you write to PowerPlant’s API, you can many-times 
be shielded from the pains of OS conversions (especially useful 
as we move towards Carbon) as well as pick up any 
advances/fixes from PowerPlant for free. 


John C. Daub love.s hi.s new WallStreet/DVD — it’s what he’s using to type this article. John is transitioning to a new position 
with Pervasive Software working on the Mac Editor portion of Tango. At the time of this writing, John has been with the 
company three weeks and is having fun! As always, you can reach John via email at <hsoi@pobox.com>, or feel free to drop 
him a line at <John.Daub@perva.sive.com> (IS won’t let him have “h.soi” ;-) 
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An iriiportanl f)iccc of, as well as a recent addition to, the 
core utilities is UAppearance. UAppearance is a strange but 
useful class for working with the Appearance Manager, 
especially Appearance Manager vl.l. In Appearance Manager 
1.1 (released as a part of Mac OS 8.5), Apple introduced 
Themes. I’hemes were a way to modify the overall cosmetic 
look and feel of your Mac (akin to the shareware 
Kaleidoscope). For whatever reason, Themes didn’t come to 
pass in OS 8.5, but nevertheless PowerPlant worked to try to 
be as Theme-savvy as po.ssible. One problem faced was how 
to support the various versions of the Appearance Manager 
(vl.O, vl.O.x, vl.l) from a unified API. Furthermore, OS 8.5 was 
PowerPC-only, which meant Appearance Manager 1.1 was 
PPC-only as well. As I\)werPlant must work on both 68K and 
PPG from the same codebase, what to do to allow ones code 
to work properly with Themes, all Appearance Manager 
versions, and possible runtime architectures? Whew! Fnter 
UAppearance, consolidating the various means for determining 
Appearance-related Information into a single-API. If you need 
to get the text color, call UAppearance::GetThemeTextColor() and 
it will Do The Right Thing® based upon compile and runtime 
options. Read the source (that includes reading tlic header, 
tcK)!) to get the low-down. UAppearance doesn’t bridge all such 
needs that might exist in the Toolbox, just what PowerPlant 
itself needs. Of course, if you need to obtain this information 
in any of your code, do use the UAppearance bottlenecks as 
they should always Do The Right Thing. 

Enc apsulated Functionauty 

Some Utility Classes work to consolidate common 
behaviors into groups and easy-to-call functions. UTextTralts 
provides the complete functionality needed by The 
Framework to work with TextTraits Resources (Txtr’). 
UWindows provides implementations of some common 
window manipulation routines, like getting the content and 
structure Rccts. UScreenPort creates a GrafPort the size of the 
GrayRgn (see UFIoatingDesktop for use). UPrIntIngMgr provides 
wrappers for some common printing needs. UKeyFilters 
provides the functionality to implement KeyFilters (as used by 
classes like LEditField and LEditText). 

UDrawingState and UDrawingUtils are two of the more 
commonly used portions of this group. If you look in those 
source files, you’ll see there’s a lot of good stuff. 
UDrawingState is mainly a collection of small stack-based 
classes for saving/restoring drawing states: GrafPort, color, 
pen, text style, clipping region, port origin. I’ll speak about 
stack-based classes in greater depth later in this article. 
UDrawingState also contains .stack-based cla.sses for 
manipulating the visRgn and the CQDProcs. UDrawingUtils is a 
general collection of routines for drawing behaviors. 
UTextDrawing performs various text renderings, akin to 
TETextBox only betier. LMarchingAnts and UMarchingAnts can 
help you implement a marquee selection (see also 
LMarqueeTask in the Constructor Additions). UDrawingUtils and 
StColorDrawLoop help to work with drawing devices so 


PowerPlant can Draw() in a device-friendly manner (e.g. 
proper rendering of widgets when they straddle multiple 
monitors each set at a different bit-depth). 

Other 

Finally, some classes don’t fit into any nice grouping. 
UAttachments contains many simple, pre-made Attachment 
classes. UProfiler contains a simple stack-based class to aid 
working with the Metrowerks Profiler. UQDOperators.h 
implements some global operators for easily comparison of 
some QuickDraw data types. Most of the routines in the Utility 
Classes are small and quick, simple to understand and use. Many 
are stack-based classes, and those hold a special bit of 
functionality within the Utility ckLs.ses. 

Exception Safety and Resource Management 

One powerful feaaire of C++ is its error handling mechanism 
— exceptions. One joy of exceptions Is diey can interrupt the flow 
of execution when something g(x?s wrong. But, this same joy c:an 
bring problems in that the normal flow of execution nonnally 
ended with a c:lL*aning uf) of resources, for example: 

( 

Handle theHandle= ::NewHandlc(kSlzc); 

ThrowIfMemFaii_(theHandle); 

DoSomething(theHandie): // Could throw an exception. 

: iDinpo.qeHandlettheHandle) ; 

1 

If DoSomethingO causes an exception to be thrown, the stack 
will unwind and ::DisposeFlandle() will never be called 
causing theHandle to Ix^ leaked with no possible means of 
cleaning it up. Not a desirable situation. You could handle 
this problem with a try/catch block: 

I 

Handle theHandle = ::NewHandle(kSize); 

ThrowIfMemFail_(theHandle); 

try ( 

DoSomething(theHandle); // ('.ouid thn)w an exception. 

1 eatch(...) { 

// Perform cleanup 
:iDisposeHandle(theHandle); 

// Rethrow the exception 
throw; 

) 

::DisposeHandle(theHandle); 

I 

The above certainly works and handles the situation, but it 
feels overkill for such a simple situation. Furthermore, in more 
complex situations than this trivial example, liilering your code 
with tcK) many try/catch bl(x:ks can get to be cumbersome. 
Instead, consider exploiting a power hook of the C++ 
language: the destructor. Whenever a C++ object is destroyed 
(by calling delete on a heap-based object, or going out of 
scope on a stack-based object). It is guaranteed that the 
clestRictor will be called. You can exploit this hook to aid in 
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the management of resources (which aren’t necessarily Mac OS 
Resources, [)ul certainly can be); this is what stack-based 
classes are all about. Let’s look at how this works in greater 
detail by examining probably the most frequently-utilized 
group of slack-based classes in PowerPlant: UMemoryMgr, and 
specifically StHandleBlock. 

'Phe basic premise behind a stack-based class is the 
constructor does something and the destructor undoes it. 
Push-Pop. Hence, stack-based. A common paradigm in 
programming is to temporarily change the state of something 
[)y saving off its current state, changing it to the new state, 
doing whatever work you needed to do, then restoring the 
original state. Such situations are prime for stack-based 
classes, and the classes of UDrawingState are perfect 
examples of this lot (StColorPenState). Other stack-ba.sed 
classes still function on the same push-pop paradigm (say 
that five limes fast!), but provide greater functionality to the 
user; StHandleBlock is a good example of this sort of class. 

StHandleBlock is a stack-based class that manages a Mac 
OS Handle. (I’m sure by now you’ve noticed the PowerPlant 
convention of naming (most) stack-based classes with an St 
prefix). The StHandleBlock constructors either take ownership 
of an existing Handle or allocate a new one (::NewHandle()). 
There are routines to manipulate the Handle, so you can treat 
an StHandleBlock object as a Handle in your code. And most 
importantly the StHandleBlock destructor disposes of ihe 
Handle. One benefit of the class is that the Dispose() method 
is smari and checks first to see if the Handle is a Memory or 
Resource Handle, calling ::DisposeHandle() or 
::ReleaseResource() as appropriate (no more need for the 
DisposeResource INIT). StHandleBlock is fairly 
straightforward, and most of your use of the class in code 
will be fairly boring and uneventful. The joy the class brings 
comes in terms of cleanup. 

Again, StHandleBlock is a stack-based class — whenever 
the object leaves scope (since you do tend to create slack- 
based classes on the stack...), the destructor for the object 
will be called. Think about the ways that you can leave 
scope. You could leave them normally, like reaching the 
bottom of the function. You could leave abnormally, perhaps 
as a goto or as a result of an error or exception. But no matter 
how you leave, the (StHandleBlock ) object leaves scope and 
its de.structor is called thereby undoing whatever you did 
(::DisposeHandle())and leaving the world in the state that you 
found it. So we can rewrite our above code snippet like this: 

i 

StHandleBlock LheHandle(kSize); 

f)oSomcthing(lheHandle): 

1 

Yea, that’s all the code becomes, and therein is part of the 
joy. The StHandleBlock con.stnictor will try to allocate a 
Handle of the requested kSize, failure resulting in an 
exception being thrown (due to the constructor that we used, 
see the source for more details). Once that returns, theHandle 
is now a valid StHandleBlock object with a Handle of size 


kSize, just like before. Through the magic of an implicit type 
conversion operator, theHandle can be passed directly to 
DoSomethingO as argument. If DoSomethingO should throw an 
exception, theHandle will go out of scope and 
::DisposeHandle(mHandle). If DoSomethingO does not throw 
and the routine exits normally, theHandle still goes out of 
scope and ::DisposeHandle(mHandle). By use of 
StHandleBlock, no functionality has been lost, and the gains 
of resource management and exception safety have been 
won. You just write it and forget it. Your code is now more 
robust, less chance for error, and Spotlight should hopefully 
find your code more agreeable (and then so should your 
customers!). 

Certainly the use of the stack-based class isn’t without 
cost (Meyers discusses costs of C++ in More Effective C++). 
There is the overhead of the object itself, the storage 
requirements (in addition to the .storing of the normal data, 
be it a Handle or Ptr or Str255 or what have you), the time 
involved to create/dispose the object. In most situations 
these are worthwhile tradeoffs. If exception safety is needed, 
if delegating the responsibility of cleanup to the o[)jeci itself 
is desired, then by all means use the classes. But there are 
occasions where it’s more wasteful to use them, e.g.: 

I 

Handle theHandle = ::NewHandle(kSize): 

::BlockMoveData(dataPtr. ‘theHandle, 

::GetPtrSize(dataPtr)); 

::DlsposeHandle(theHandle); 

1 

In the above code, theHandle was allocated, used, and 
disposed of with no chance for the flow of execution to 
change unexpectedly. Using StHandleBlock here is certainly 
legal and fine to do, but is not as efficient as is direct 
Toolbox access. Base your approach upon the context. 

If you like StHandleBlock, check out StTempHandle and 
StClearHandleBlock which are subclas.ses of StHandleBlock 
that allocate a Handle in temporary memory and allocate a 
cleared Handle, respectively. Related to StHandleBlock is 
StPointerBlock (and StClearPointerBlock); these classes behave 
similar to their Handle counterparts, bui maintain a Mac OS 
Ptr rather than a Handle. UMemoryMgr al.so contains a 
PowerPlant version of std::auto_ptr<T> called 
PP_PowerPlant::StDeleter<T>; StDeleter is functionally 
equivalent to auto_ptr, but exists to minimize dependencies 
upon the C++ standard library. StHandleLocker merely locks 
a Handle and en.sures a proper restoration of the Handle state, 
which allows StHandleLocker objects to be ne.sted .safely. 
Furthermore, StHandleLocker implements Handle locking in a 
.scheme consistent with Apple 'LechNote 1122, which 
discusses the proper way to lock a Handle. 

Related to UMemoryMgr is URegions. URegions is 
comprised of two classes: StRegion and StRegionBuilder, 
providing similar functionality as StHandleBlock, but specifically 
tuned towards working with Mac OS Regions. Not only is the 
creation/destRiction of the RgnHandle accounted for, but all 
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manner of operator overloads and methods are provided to 
facilitate working with Regions — never has working with 
Regions been so simple! StRegionBuilder works in conjunction 
with StRegion to facilitate the on-the-fly creation of Regions. As 
you use these classes in your own code, you start to see how 
through their use throughout your code, the tighter the web 
they weave to keep code clean and properly coping with 
unexpected problems when they crop up. 

UMemoryMgr is a prime example of how slack-based 
classes can help you belter manage your resources, eliminate 
memory leaks, eliminate stale state information, be 
exception-safe, and write more robust code. These sorts of 
utility classes should find their way into your toolbox as need 
for them arises. Explore. If you’d like to learn more about the 
concepts these clasvses are based upon, check out <7++ FAQs 
by Cline and U)mow, and Scott Meyers’ excellent books 
Effeclive C++ and More Effective C++. 

More Than Utility Classes 

There are a good many “utility” classes throughout 
PowerPlant; it’s not isolated to only tho.se files and clas.ses 
located with the Utility Classes folder. Many of the other 
folders contain “ulilily” type classes, and many files have 
little utility claSvSes and/or methods to ease working with 
other classes within the .same file. 

The Support Classes folder is a prime example of another 
set of “utility” classes. With classes for working with the 
Clipboard (LClipboard), GrowZones (LGrowZone), tracking 
the mouse (LMouseTracker), manipulating windows 
(UDesktop and UFIoatingDesktop), and of course we can’t 
forget LString. 'Ihe In Progress folder also hou.ses a number of 
utility cla.sses (al least at the lime of this writing, looking at 
PowerPlant 2.0). There are utilities for working with graphics 
(LGAIconMixin, LGATitleMixin, UGAColorRamp, UGraphicUtils), 
menus, Stuffli archives, contextual menus. AppleEvent 
Classes folder has UAppleEventsMgr and UExtractFromAEDesc. 

Contained within many source files are utilities for the 
particular main class. In LModelObject.h, you’ll find the 
StLazyLock and StTempTellTarget classes that facilitate 
working with LModelObject. TSharablePtr is a smart-pointer 
class for working with LSharable objects (reference 
counting). And the lists can go on. 

Fin 

Utility Classes are an essential part of any framework. 
They are tidbits of code that help make our life a little bit 
easier by letting us write one line instead of ten, automate 
some process, facilitate another process. They help our code 
be more robust through exception-safety and resource 
management. They help us out in the long run becau.se we 
can write more trouble-free code from the start, which means 
less time wasted debugging and more time spent refining the 
features of your killer app. 

T hope this brief lour of the Utility Classes in PowerPlant 
has shown you something new, perhaps some unexplored 


area of PowerPlant. Stack-based classes are a great part of 
the Utility classes and are probably a good place for you to 
start to get familiar with these cla.sses. Rut don’t slop there! 
Read the source code and see what else PowerPlant has to 
offer. There are lots of nooks and crannies in PowerPlant that 
hold some really neat stuff. The more you know, the more 
you can do. 

Haf^py programming! 
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GOT BUGS? 

...and you're drowning in paper 
trying to keep track of them? 

You need BusLink! 

• BugLink is a client/server application allowing you 
to connect developers, testers, and support engineers 
anywhere in the world. 

• Intuitive user interface gives you the information you 
need at a glance. 

• Fully customizable database— add the fields you need 
to each project. 

• Custom TCP/IP protocol minimizes network 
traffic— ideal for dial-up connections. 

• Client applications can operate 'off-line'— allowing 
bug entry and modification even when not connected to 
the network! 

• Cross platform— set up mixed Macintosh and Windows 
environments in minutes with no additional software 
needed! 

• Try before you buy. Download and try risk free for 
30 days from http://www.pandawave.com/bl/ 

A 5 User License starts at $299; that's only $60 per person. 

The PandaWave 

http://www.pandawave.com 
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EXPLAinilT^*" 


By Kenneth Slallenfield 


NetBooting and You 


Or, how I learned to stop 
worrying and Jove the server 


Welcome 

Imagine yon manage a room of 
computers in your local junior high school 
that gets used by different classes of 
students during each day, sometimes just 
for word processing or web surfing, and 
other limes for student programming 
work. After school, games gel played on 
the machines and teachers lypL' up tests 
and notes. You, as manager, have several 
problems, and many of them involve 
somehow making sure that every 
computer in the lab has the correct 
software installed, that the folks in front of 
each computer have access lo I his 
.software, and that the students can’t read 
the teacher’s or other .student’s documents. 

Mac OS X Server, with its NelBool 
feature, hopes to make your life a bit 
easier. It allows you to in.stall .software on 
one computer, once, and have it available 
on any computer in the room. It allows 
you K) require .students and faculty to log 
in to computers before using them, and 
gives different users and grou[)s of u.sers 
acce.ss to different applications. Some 
users might only be allowed to run the 
applications their teacher has approved; 
others might be allowed to run anything 
installed. Since It provides a robust, 
centralized file server where everyone 
stores documents, users can sit down in 


front of any computer and get to their Information. And, since it 
doesn’t allow users of the computers to make any permanent 
changes to the software on any particular computer, tliere’s no 
risk that a budding prankster in third period will manage to 
coraipt the installed software so that you have to rush to fix it by 
fourth pericxl, becau.se a simple restart will restore the computer 
to the setup you originally created. 

NetBoot should also apix:al to other u.sers. Businesses seeking 
to reduce support costs, cylx?r cafe’s that want to set up a gn)up of 
computers which c:an not lx* corrupted, or developers seeking a 
quick way to rapidly test a|)plications in a clean environment. 

'I'his article will give you a background for Mac OS X Server, 
de.scribe how NetBooting works from a user and a technical 
perspective. It will al.so point out .some things that you should be 
aware of as a developer if you want to be NetBoot friendly and 
point out some developer opportunities that involve NetBoot. 

BACKCiROlJNI) 

NetBoot is a feature of Mac OS X Server, and is actually a 
synergy of .sevenil of the server features of Mac OS X togetlier witli 
some support in the Open Firmware of recent Macintosh 
computers and some new additioas to Mac OS 8.x system software. 

Mac OS X Server also provides web seiYices via an Apache 
web server, file transfer services via ftp, and a WebObjects 4.0 
environment including a 50-transaction-per-minule license and 
Software Development Kit. Also included is a j')rerelease of the 
QuickTime Streaming Server for sending many video and 
audio streams of data to multiple computers. A full 
description of Mac OS X Server can be found at 
<http://www.apple.com/macosx/sGrver/>. 

A User’s View 

When a user sits down in front of a NetlkK)t computer, the 
first thing they will notice is that it l(K)ks and lx)ots pretty much 
like every Macintosh. Starting up several computers from a 
NetBcKX server is about as fast as starting up from the kxral hard 


Keith Stattenfield toil.s within the ca.sile waifs of Apple Computer in Cu|X^rtino, California, fixing bug.s and mi.sfeatiires in each 
Mac OS 8.x release. His exploits can lx‘ observed in real time at <http://www..stattenfield.org/keilhcam/> 
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disk. Users are asked to login with a username and password, 
and then find themselves in one of three environments — the 
standard Finder environment, a “restricted” Finder environment 
where many commands (such as deleting files) are disabled, or 
a simplified “Panels” environment. In the “Panels” environment, 
an administrator has defined exactly what applications are 
available to a user, and the user sees a series of icon buttons, 
which they can use to start each allowed apf)lication. 


Welcome to Mac OS 


Name: [Keith ~ 
Password: ••••• 
Server: [ ks server 


Shutdown Change Password 


Figure L Usen are required to log in with a name and 
passtvord before they are allowed to access a NetBooted computer. 



Log in 


When a user logs in, the Macintosh Manager software 
copies down any saved Preferences and certain other files from 
the NetB(X)t server onto the computer, sets up the app^earance 
and desktop for the user, selects the correct printer for this user, 
and performs other initialization to personalize the computer. 
When the user logs out by choosing “Quit and lx)g Out” from 
the bottom of the File menu in the Finder, or by shutting the 
machine down, any changed preferences are copied back up to 
the server, and the computer is returned to a common state. 



Figure 2. Users gel a progress bar as the system copies 
down their unique preferences and sets up the computer 
unth their iruiividual settings. 

Once in tlie Finder, the aser will see two ’disks’ on their 
desktop with interesting icons — the “Network HD” and the 
“Applications HD”. The “Network HD” is the lxx)t drive and 
contains a Mac OS 8.5 System Folder and whatever else the 
administrator has chosen to put there. The Applications HD is 
read only, and contains the applications which ship with Mac OS 


8.5 (Internet Explorer, Outlook Express, etc) and whatever the 
administrator has j)ut there as well. 

Users will notice that if they copy files onto the startup 
drive, or download files from the internet onto the internal drive, 
that none of the changes they have made to the staitup drive are 
present after they have restarted the computer. 'Itiis is especially 
apparent with extensions, control panels, etc, since they must 
restart the computer in order to use these items. 

Administrators have a significant amount of control over 
the setup of the computers. Individual users can not install 
extensions or control panels, nor can they disable the ones 
that are already installed. Privileges can be set on a per-user 
or per-group basis, and each user can belong to one or more 
groups. Users can have print quotas, and might be restricted 
to certain printers. The also may have file space quotas on the 
server. A particular user or group might only be allowed to 
run certain applications. On computers which have CD or 
floppy drives, their use can be restricted so that only 
approved CDs are used, or to disallow floppy use entirely. 
Administrators can also remove, with an extension, the local 
hard disks from the user desktops. 

The risks of viruses are lessened in a NetBoot 
environment, because end users do not have persistent write 
access to the boot disk nor to the applications disk. F.ven if a 
user manages to infect a particular computer with a 
conventional vims (like MBDF , upon restarting that computer 
will throw away eveiy change made by the user (including the 
complete set of infected applications) and go back to the 
uninfected setup originally created by the administrator. 
However, document-based viruses, like Microsoft Word macro 
viruses, or applications which the users place in their space on 
the fileserver, will still exist so NetBoot does not entirely 
eliminate the problems with computer viruses. 

Administrators install .software by using a utility called the 
“NetBoot Desktop Administrator” application. When run by an 
administrator on a NetBoot client, this application places that 
particular computer into a ‘persistent mode’, and all future 
changes made on that computer are preserved across reboots. 
The administrator can install software, remove software, 
rearrange or delete files, etc. When happy with the new setup, 
the administrator mns this application again and commits the 
changes made so that all users will see them the next time their 
computers reboot. 


The Technical View 

A NetBooted computer implements these features in several 
ways. Only recent Macintosh models iMacs and later) are capable 
of NetBooting, because the lowest level of support necessary to 
NetBoot is only implemented in the Oj)en Firmware for these 
machines at this time. In these rnacliines, at startup the code in 
Open Firmware will look at where tliey are suppose to startup 
from, notice that it is a NetBoot server, and will begin the pr(x:ess 
by sending out a special Ethernet BootP packet asking if a 
NetBoot server is available. If there is a server in the same subnet, 
it will reply to the client with an IP address tlie client can use as 
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well as informalion about what disks will appear on the client 
once it boots. After getting an IP address, a client will download 
a copy of the Mac OS ROM file from the server and then mount 
the Network HD and Applications HD disks from the server. 


□ Disk —= H 


Select a Startup Disk: 



Figure 3. A remsed Startup Disk control panel allows users to 
select a NelBoot server as the start up device. 

From the point of view of the Mac OS, the boot and 
applications disks are using a normal, block oriented disk 
driver named “LANDisk”, which uses an Appleshare File 
Protocol over TP (AFP/IP) connection to the NetBoot server to 
get and put data onto the ’disk’. However, this AFP/IP session 
is distinct from any ‘normal’ Appleshare session that may be 
opened on the computer. 

At the lowe.st level, the system is using a special version of 
the Ethernet hardware driver which can allows the driver for the 
network disks and Open Transport to share a single TP number. 
Incoming packets are distinguished [:)ased on the prot(K:ol and 
port number. Packets destined for the AFP session for the 
.LANDisk driver are not visible from Open Transport, llie AFP 
session that is used by the .LANDisk driver is not accessible from 
within the Mac OS proper. 

On the server, the “Application HD” and “Network HD” are 
stored as uncompressed, read only DiskCopy disk images. A 
client opens a read-only connection to each of these over the 
AFP/IP .session, and tlie block driver translates read requests for 
a given bl(x:k into a read from a given offset in the appropriate 
file. 'Fhe non-persistence of the startup disk is accomplished 
almost entirely by the client. When a client starts up, if a 
particular volume is sup{X)se to be non-persistent, then the 
server gives the client two files for that volume — one is the 
DiskCopy image, which is opened read only, and the second is 
an empty, wTiteable file. The client will write any changes to the 
disk into this second file. It will read a block from the first file 
unless the block l)eing read has already been written to, in 
which case it reads from the second file. This second file 
essentially becomes a shadow and contains only the changes 


from the first file. 'I'he contents of this second file are discarded 
whenever the client reboots, so the changes made disappear. 

The system also patches a number of traps to force users to log 
in and log out, and to prevent users from tampering with the system 
folder in an attempt to circumvent tlie security of the system. 

CoMPAHBiiJTY Issues 

Hopefully, we at Apple did enough work to maintain 
compatibility that most Macintosh software should w^ork 
correctly in the NetBoot environment. However, no system 
update or change is ever free of changes that can affect the 
existing base of applications, and this one is no different. In 
testing the NetBoot environment, we found that most 
applications worked correctly, although some had minor 
problems. Applications which attempted to write back to their 
own data forks failed when placed on the read-only Applications 
drive, but also would have problems ainning from a locked 
fileserver prior to the release of the NetBoot server. We found a 
few applications which attempted to write back to their own 
files only on first launch as |)art of a user personalization or 
serial number entry process, in which ca.se they would fail. 

One of the implications of a NetBoot environment is that 
the ‘local’ hard drive is not the primary data storage for a user, 
since users may move around from computer to computer but 
want their data always accessible. While the current .setup with 
user files stored on a fileserver volume works ok, it is not 
neceSvSarily the most appropriate .solution. For example, in a 
NetBoot computer lab it is probably better to set eveiyone up 
with email accounts on a IMAP server and have them read their 
mail with an IMAP client instead of .setting everyone up with 
POP3 accounts. The IMAP architecture has users keep their 
email on a central server instead of downloading it into a 
number of private but still .server ba.sed POP3 databases. You 
may find that this mentality cau.ses you to rethink how the 
applications you produce are designed and used. 

Things to Think About 

There are still some things that you, as a developer, need to 
be aware of. If you store preferences outside the Preferences 
folder, then these likely w'ill not be saved and restored for each 
user as they log in and out. If your preference files are 
exce.ssively large, then u.sers may complain that your software is 
causing excessive log in and out times. 

If your applications use the Icxral hard drive to cache data, 
then make sure that the user can control where this cache is 
created — othei'wise, NetBoot users will find that their 
applications perform poorly as they rebuild this cache each time 
they use your application. 

Net Booting opens new opportunities for developers and 
value-added resellers. Early on, many of the users of NetBoot 
setups will be .schools or computer lab .set-ups. Over time this 
should increase and may encompass busine.ss users, especially 
in environments where centralized control and workflow 
management is important. So, a pre-press environment may 
decide to use a NetB(X)t server for many of the users in order to 
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insure that every user has exactly the same set of fonts and 
applications, with the correct versions, running at all times. 
For example, if schools use the NetBoot architecture, that 
they may also want to buy good web filtering software 
(perhaps server based, combined with a good web proxy, 
since bandwidth is still rather limited in schools). 

NetBoot also shifts the focus for where data is stored from 
local files onto fileservers and onto other kinds of servers. A 
calendar application which stores all of its data in files in the 
system folder is not as useful in a NetBoot enviromnent as one 
which can store data in a file on the fileserver. 

It is possible a single user will be logged onto more than 
one computer at a time. The current NetBoot environment 
doesn’t handle this situation very gracefully, but does allow 
it to ha[)pen. If a user logs onto two computers, and docs 
something that changes a particular file in the Preferences 
folder on both computers, there is not concept of merging 
these changes — the files with the later modification file 
dates will be kept and the earlier ones will be discarded. 

For the terminally curious, you can tell if your system is 
NetBooted with GestaltO. 

Boolean I.qSystemNetBooted () 

( long value; 

if ( (Geslalt(gestaltSplitOSAttf, & value ) == noErr) 

&& 

( value & ( 1 << 

gestaltSpliiOSBootDrivelsNetworkVolume) ) ) 
return true: 

return false; 

1 

'Fhere is presently no easy way to tell if the system is booted 
persistently or non-persistently. Eventually, there will be a 
gestalt selector with this information. 

Documentation and Licensing Issues 
You may also want to make changes in the 
documentation for your products, to indicate whether you 
have tested them in a NetBoot enviromnent and to detail any 
oddities during the install or configuration. 

Licensing of products for use in the NetBoot environment 
requires some thought, since the ‘same’ application is installed 
once into the master image but then gets used on a number of 
computers. You might consider selling a license for a single 
NetBoot server, allowing all clients of the sei*ver to use the 
software, or you may want to recommend a product like 
KeyServer (from Sassafras Software, <http://www.sassafras.com/>) 
that can monitor and restrict use to only those number of 
copies which have been purchased. Licensing is especially 
important in a regimented environment like a school computer 
lab, where most users will probably be expected to use the 
same software simultaneously. 

Similarly, applications which require serial numbers and 
insure that only one copy of the application is running with 


a given serial number have a serious problem if they write 
the serial number back into the application’s data files, since 
each computer booted from a NetBoot server will use exactly 
the same set of applications, lb this end, Apple has 
recommended for some time that applications do not write 
back to themselves. With the advent of NetBooted 
computers, it’s useful to also add that applications with serial 
numbers should write their serial numbers to their Preference 
files. This way, a user who has purchased an application will 
enter it’s serial number when they use the application the 
first time, and the serial number will move around with them 
as they log in and out from each computer. 

Future Directions 

On the client side, Apple expects to eliminate the 
necessity of copying preference and other files back and 
forth as users log in and out. In order to do this, we will 
change FindFolderO so that it returns a vRefNum and dirlD 
which point to a folder on a server when you call FindFolder 
( kOnSystemOisk, kPreferencesFolderType, ... ). Your code 
must use both the vRefNum and dirlD returned by 
FindFolder in all cases. Do not assume that the vRefNum for 
special folders, including those in the system folder, is -1. 

Fuaire versions of the Mac OS may include more security, 
both to prevent one user from accessing the files and folders of 
anotlier user, as well as protecting some parts of the system (like 
the System Folder) from being accessed by users who do not 
have the authority to make changes to the computer. 

Many users have also requested that NetBoot client 
computers use DHCP instead of BootP to acquire their IP 
address, and this is something which Apple is looking into doing 
in a future version. Additional authentication, and opening up 
the authentication that is provided, is also being considered. 

On the server side, any move to DHCP would have to be 
mirrored with DHCP support and the user interface changes 
to configure DHCP. It is also desired to produce a solution 
that can run with IP only, eliminating the need to use 
AppleTalk in a NetBoot setup. Also, future versions of Mac 
OS X server should support gigabit Fthernct and more 
networking connectivity. 

Wrapping Up 

NetBooting is a new capability for Macintosh computers. 
At the moment, it will appeal most to administrators and to 
lab-type computer settings, but over time, as more Macintosh 
computers are capable of being booted from the Network 
and as fast, ubiquitous networks begin to appear, the ability 
for users to get to their data in a seamless way no matter 
where they happen to be will become very important. Your 
applications probably already work in a NetBoot 
environment, but with a little work you may be able to give 
your users a fabulous experience. K1 
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TOOLS OF 
THE TRADE 


By Daniel Jalkul 


MacsBug Revisited 


This is not your father's 
low-level debugger 


Introduction 

MacsBug is an extremely powerful, 
low-level debugger which Apple maintains 
and distributes for free to developers of 
Mac OS software. From its humble 
beginnings as the Motorola Advanced 
Computer Systems Debugger in 1981, it 
has evolved into the debugger that many 
developers lx)ih inside and outside of 
Apple depend upon to gel their jobs done. 

The aim of this aiticle is not so much 
to introduce MacsBug as it is to 
reintroduce it. Enough basic intrcxluctions 
to MacsBug have been written that I don’t 
believe a repetition is necessary. If you are 
Interested in a detailed description of 
Mac:sBug’s basic features, I suggest you 
consult one of the publications mentioned 
at the end of this article. 1 suspect that 
most of you have heard of MacsBug, and a 
majority of you has probably used it to 
varying extents. 1 hope to provide 
.something that each of you can u.se to 
further your use of MacsBug in the battle 
against buggy code. 

In recent years, MacsBug has 
received less attention from Mac OS 
technical publications than it did in the 
past. Many developers have .switched to 
using source-level debuggers like the 
one included with Metrowerks 
Code Warrior. Those debuggers, while 
very convenient for the majority of bug 
diagnoses, have a limit to their 
usefulness. MacsBug continues to 


prosper because of the elegance with which it allows 
developers to overcome limitations of higher level debuggers. 
This article is divided into three .sections, each of which 
discu.sses a different aspect of this elegance. 

'llie first section is a high level discTission of the tliinking that 
gcx.‘s on when diagnosing a bug, and a de.scription of .some basic 
approaches you can lake to work out the diagnosis with MacsBug. 
The second section extols the viitues of MacsBug’s extensibility, a 
feature that should apjx^al to those of you with highly six^cialized 
or uni:)rediciable debugging needs. Finally, the third .section divulges 
some of the exciting fc*iitures that Mac'sBug has gained in tiie pa.sr 
couple of years, which .should convince the biggest MacsBug 
skeptic that .something here deseives a second look. 

Before you experiment with any of the functionality 
de.scribed in this article, 1 highly recommend downloading the 
most recent version of MacsBug from Af)ple’.s MacsBug web site: 
<http://developer.apple.com/tools/debuggers/MacsBug/index.html>. 

Part One: The DEUucKiiNCi Mindset 

I don’t know anybcxly who has mastered MacsBug. Like 
Herman Hesse’s Siddharta and his pursuit of nirvana, the mastery 
of MacsBug is a lifelong journey for which there is no apparent 
end. This humbling reality, while disheartening, must not prevent 
you from using what you do know to battle any bugs you 
encounter along the way! Like chess, the basic tcxils can be easily 
taught, but the .secrets of winning are learned only by developing 
a mindset which allows you to apply simple techniques in new 
and exciting combinations. In this .section, I will de.scribe a basic 
approach to debugging in MacsBug, wliicli you can expand 
upon as you develop your own debugging .style. 

.MacsBug is typically encountered by one of two mechanisms; 
intentional or unintentional CPU exceptions. An exception is jirst 
what it .sounds like — a deviation from the normal course of 
operations. Intentional exceptions occur when you, the 
[programmer, premeditate an event that causes Mac-sBug to interaipt 
the execution of cxxle and display the state of tlie computer on the 
.screen. Unintentional exceptions cKXTir when .somelxpdy’s code 
crashes. Tlie mentality for dealing with either is different. 


Daniel Jalkut is a software engineer in the Mac OS System Software group at Apple Computer. In his spare time, Daniel works 
on .solo projects under the moniker Red Stwaler Softu>are, and enjoys Ix^ing a pede.strian in the Ix^autiful city of .San Francisco. 
You can contact him at <jalkul@sirius.com>, or view his home page at <www..siriu.s.com/~jalkiil.> 
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when you break into MacsBug intentionally, either by a 
breakpoint (“tvb”, “atb”, “br”, “brp'') or a programmed exception 
in your code (Debugger or DebugStr), you typically want to 
examine the state of things at a particular point in your code’s 
execution. Typical reactions to an intentional MacsBug entry are 
to check that the parameters of a function look correct (e.g. “dm 
r3”), that the heap is not coraipt (“he”), or to step through (“s”, 
“t”) code one instaiction at a time and ensure that your code 
docs what you think it should. MacsBug is perfectly suited to 
debugging in these circumstances, but since this type of 
debugging is especially well suited to a source-level debugger, 1 
will focus only on unintentional interruptions (crashe.s). 

When MacsBug is encountered as the result of a crasli, you 
don’t have the same luxury of understanding the circumstances 
as you do in an intentional interruption. Three very important 
questions to ask are: “What caused the crash?”, “Where am I?”, 
and finally “How did 1 get here?” The answers to these 
questions will greatly increase the odds of pinpointing the 
problem. Let’s discuss some basic strategies for answering each 
question in turn. 

What Caused the Crash? 

MacsBug interrupts the execution of code when that code 
violates the rules of the CPU. If you are lucky, MacsBug’s 
explanation of the crash will provide some insight into the 
problem. MacsBug displays the explanation immediately after it 
appears, and the explanation can be repeated by issuing the 
“how” command (a caveat is that MacsBug forgets this 
inibrmation as soon as you step or trace). Usually, the 
information provided is broadly useful, but doesn’t specifically 
pin down the cause of the crash. Among the most common 
causes of crashes are memoiy exceptions and illegal instructions. 

Memory exceptions occur when a piece of code tries to 
read or write from memory that either doesn’t exist (is not part 
of I he address .space) or which exists but is off limits to the 
crashing code. When this is the cause of a crash, the basic- 
approach is to look at the instruction that is causing the crash, 
and tiy to figure out where the bad address came from. If yoirre 
lucky, the address was the result of ihe last subroutine called, 
and you know the culprit immediately. If you’re not so lucky, 
finding the (origin of the address might involve tracing back 
through hundreds of lines of MacsBug disa.ssembly, aemss 
several levels of subroutine calls. 

illegal instructions are sequences of bits that make no sense 
to the CPU. The CPU depends on receiving a stream of 
instructions that corresponds exactly to actions it knows how to 
perform. For instance, the hex value 0x38600000 means to the 
PowerPC pr()C'e.ssor “put the value zero in register 1 * 3 ”. When the 
PowerPC processor receives a hex value like OxHTITHI, it 
means nothing to the CPU so it causes an illegal instruction 
exception. When you reach MacsBug because of an illegal 
instruction, you are usually facing a bug where the program 
counter is pointing to data instead of code. There is a small 
chance that your compiled code contains illegal instructions, but 
this is unlikely unless there is a bug in the compiler, or you 


compiled for a specific CPU (Motorola 68030 for instance) and 
tried to run on a different CPU (Motorola 68000 for instance). 
Since the overwhelming majority of times you hit an illegal 
instruction will be because you are executing data instead of 
code, the solution to this problem requires answering the 
(juestions “Where am T?” and “How did 1 get here?”. 

Where Am I? 

You know why the computer crashed, but this information 
is useless if you don’t know the culprit code that caused it. There 
are three types of crashing code in this world: your code, other 
people’s code, and data. 

If you are building with symbols and traceback tables 
enabled, as you should be for pre-release builds, MacsBug will 
make it in*imediately clear whether you are executing your own 
code or somebody else’s. If MacsBug prefaces the disassembly 
in the program counter display with a symbol, and you 
recognize the symbol as one of your routine names - 
congratulations your code crashed! 

It Came erom Beyond... 

If there are no symbols, and the code doesn’t scream out to 
you what it does (immediate recognition of a.s.sembly code’s 
purpose is an uncommon, but real skill), you are going to have 
to dig deeper to find out exactly whose code it is. An immensely 
iLseful MacsBug command is the “wh” (short for “where”) 
command, which identifies as best it can the characteristics of a 
location in memory. Commonly, this command is issued without 
a parameter, which catrses it to give information about the 
current location of the program counter. The output of the “wh” 
command ranges from “very useful” to “not so useful, but I’ll 
take it” to “pretty darn useless.” 

In the “very useful" category, when the code you are 
executing is part of a PowerPC code fragment, the name of 
the fragment will be displayed along with the offset into the 
fragment of the particular line of code. The name of a 
PowerPC code fragment can be either an af)plicatic;n name, 
a library name, or the logical name given to any piece of 
PowerPC code that is stored in a fragment. Usually, the name 
will implicate your application, another application, or a 
piece of System Software code. 

If the code is 68K code or is not part of a CFM libraiy, the 
result of the command may be simply information about the Mae 
OS memory manager block in which the code resides. This is 
less immediately useful than a library name, but you can 
sometimes figure out who.se code it is by examining the memory 
block for clues. In particular, if the memory block is being 
tracked by the Resource Manager, then additional information 
about the resource, including the file it came from, are included 
in the output of the command. A good second stab is to take a 
look at the first several bytes of the memoiy block, which 
sometimes contain symbols or character codes (e.g. ‘PLUG’, or 
‘“Apple Menu Options”) which will sometimes bring you closer 
to the identity of the code’s owner. 
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In worst case scenarios, the code you crashed in is not even 
code that the Mac OS memoiy manager keeps track of, and all 
MacsBug can muster is that the address is “in RAM but not in a 
known heap.” Aside from displaying memory around the 
program counter and hoping for a lucky find, you are pretty 
much lost. This doesn’t mean you aren’t going to find the bug, 
it just means you have to do so without the benefit of knowing 
what the crashing code is. 

Exjkcuting Data 

Since ckita and memoiy coexist in the same address space of 
the Macintosh, and since the Mac OS provides only limited memory 
protection (for file-mapped PowerPC libraries), it is entirely possit)le 
tliat the CPU will be handed a chunk of data and be asked to 
exec:ute it as code. If you are at all familiar witli the assembly 
language for tlie CPU you are debugging, it will usually Ixf 
immediately clear whetlier you are in data or code memory. Wlien 
you kK)k at the code at and around the program counter (“ip”), does 
it look like assembly language or does it look like MacsBug tiying 
to translate monkey talk to a rhinoceros? Common giveaways are if 
the disa.SvSembly contains a lot of “ORI.B” instnictions (68K), or a lot 
of “dc.l”” instructions (PowerPC). This is because the hex 
representations of tliese instructions are 0x00000000, and data 
memory usually contains a lot of zeroed-out memoiy. 

If the memory looks like data, you are one step further to 
solving your bug. Usually the data contains patterns or text 


which are characteristic of the code that owns it. Find the 
beginning of the memoiy block with the “wh” command, and 
display memoiy from the beginning of the block until you find 
something that looks incriminating. Whether you can cinch the 
owner or not, it is time to move on to the next stage. 

How Did I Get Here? 

If you have been lucky, you now know the fundamental 
cause of the crash, and you know whose code it is. Tliat 
knowledge is mostly useful for providing cities to answer the 
ultimate question: “how did my cute fuzzy bunny code get 
coerced off its path into the cruel, crashing world?” Unless the 
nature of the crash or the location of the code was telling 
enough to reveal an obvious solution, you must now attempt to 
turn back the clock and study the sequence of events that led 
up to the crash. Fortunately, a time machine is built into most 
calling conventions in the form of stack based link addresses. 

When a subroutine is called, the caller needs to communicate 
to the subroutine how it will return control to the caller. It is 
abundantly common for this infomiation to be passed along on the 
stack. As each subroutine in turn calls its own subroutines, a bread 
cnimb trail is left that snakes all the way back up the stack to the 
original caller. Fxamining this trail is referred to as performing a 
“stack crawl.” If you were really hard up, yoLi could display 
memory from the stack pointer for several hundred bytes, reason 
out the math implied by the values in the various positions, and 
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determine for yourself which parts of the stack refer to return 
addresses. Fortunately, MacsBug does a fairly good job of doing 
this with its ‘sc’ command. 

The “sc” command was originally only able to examine 
the stack for 68K calling conventions, but today it is capable 
of looking for both 68K and PowerPC subroutine calls, and 
listing them both in the same stack crawl listing. In the output, 
each line represents the location of an instruction that caused 
a subroutine to be called. The last entry displayed is the last 
subroutine call MacsBug could decipher from the slack. If you 
look at the list from bottom to top, you are examining the 
subroutine history, from most recent to oldest, that led to this 
point. Generally, you are looking for a piece of code that 
looks like it is yours. If you find it, disassemble the code at 
that address (“ip <address>’’) to see if you can figure out 
exactly which of your code it is. Once you determine this, 
your strategy shifts from unintentional to intentional 
debugging - move on to a source level debugger if you so 
desire. You can now .set break points at the crashing 
subroutine call and reproduce the crash on your terms. 

TherfAs No Stack CrawiJ 

Sometimes, as you sliould expect by now, things do not 
work out quite so peachy. The stack and link registers are 
sometimes in a state such that MacsBug is of no help in 
examining the stack crawl. Situations such as these call for 
desperate actions. Even if MacsBug refuses to produce a useful 
stack crawl, you can search for clues by looking at the link 
register contents yourself. Remember the “wh” command? 'fry 
“wh Ir” to get information about the address in the link register, 
and “ipp Ir” to disassemble the code surrounding the address 
(and hopefully the code that got you where you are). 

MacsBug also provides a second stack crawl command, 
“sc7”, for situations where the first does not pan out. Its output 
is identical in structure to that of “sc”, but it is much less finicky 
about what constitutes a “return address” on the stack. The “.sc” 
command actually iterates backwards up the stack, examining 
the locations which algorithmically (based on the well-defined 
calling conventions) should point to code which called a 
subroutine in the call chain. The “sc7” command, on the other 
hand, will examine et^er)) address on the stack, and as long as 
the code an address points to appears to Immediately follow an 
A-trap or subroutine call, it will list the address as a “possible 
return address.” 'fhus, the results of the “sc7” command need to 
be taken with great skepticism, but as I .said, this is a command 
for desperate situations. 

I Mean There’s No Stack Crawl! 

If the stack crawl is not panning out in any way, shape, or 
form, there is another technique that may be of aid. For 
whatever reason, the code you crashed in is just not conducive 
to the usual stack crawl analysis. If the crash you are debugging. 


however, can be temporarily avoided, then it may [)ode well to 
circumvent the crash, trace until the code you are executing is 
returned from, and see if the stack at this point is in better shape. 
If not, and if your crash-workaround la.sts, just keep tracing until 
you do get some place interesting! 

Crashing code can be avoided either by jumping past it 
(directly setting the PC register to a later address, e.g. “PC = PC 
+ #12”), or by manipulating the registers such that a crash does 
not occur (put a valid address like MacsBug’s built-in “playmem” 
in the register that is causing a memory exception). As you 
become more comfortable with direct manipulation in MacsBug, 
you will find that your debugging options increase immensely. 
Be aware, though, that you can make a bad situation worse by 
trying to “fix” things yourself in MacsBug. Hopefully, if you arc 
reading this article, you understand that the risks of data loss and 
corruption are higher than average on the machine of a 
programmer. I am usually more interested in getting the bug 
fixed than playing it safe with my computer, but then again, 1 do 
make regular backups! 

Part Two: Custom MacsBug Features 

MacsBug has always been evolving. Three important features 
of MacsBug - the ability to define macros, the ability to define 
templates, and the ability write dcrrids - have enabled MacsBug 
to evolve, meeting the needs of programmers over the years with 
relatively few changes to the core of the program. 1 shall now give 
an over\aew of these features, because MacsBug simply can not 
be appreciated without understanding these gems. 

Macros 

A MacsBug macro, like a macro in other programs, is a 
word that is translated when it is evaluated to mean something 
else. A simple example is the “windlist” macro. You might type 
this and assume it is a command that is built into MacsBug, but 
it is in fact a macro! Macros are defined by resources of type 
‘mxbm’, several of which are included in MacsBug’s own 
resource fork. The list of macros that MacsBug knows about can 
be displayed by typing “med” into MacsBug. If you look at the 
resulting list, you will .see the meaning of the “windlist” macro is 
defined as “dm ©WindowLisl WindowRecord”, where “dm” is a 
built-in MacsBug command, “WindowList” is another macro 
defined as the number 0x09D6, and “WindowRecord” is a 
template. This simple macro, then, means “display the memory 
pointed to by an address at location 0x09D6, and format the 
contents of the memory with the WindowRecord template.” 

Templates 

Templates, packaged in resources of type ‘mxwt’, contain 
information about how to format memory that is displayed by 
MacsBug. Using the MacsBug “dm” command (display 
memory), a template is invoked by typing its name as a 
second parameter, after the memory address you wish to 
display from. Without a template, MacsBug uses a default 
output structure, which consists of lines of hex values with an 
ASCII translation to the right side. Often, a more readable 
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formal is preferable. Specifically, you would prefer a formal 
as similar as possible to the structure definition in your code. 
In the case of WindowKecord, a simple memory display 
produces die following output: 


Macsikig, type the “demd” command itself. The result is a list of 
die commands at your dispo.sal. 'Ib get help on any of them, 
type ‘'help [name of demd]" (or jusl “? [name of dcmdl”), which 
wi[| cause the demd itself to explain its own functionality. 


dm (Window!isr 

Displaying memory from W9D6 

005D45D0 0000 0071 DE40 COOO 0071 DF04 0000 8000 

00i»D4bE0 0000 0000 0094 0068 00/D !)DD8 0000 2DBC.i*h*l]y** » 

003D43F0 0071 DE24 0000 0000 0000 FFFF FFFF FFFF •qfi$ .. 

005D4600 0064 005C 0001 0001 0008 0058 73BO 005D .d.\.Xs«>.l 

005D4610 431C 0000 0001 0000 0001 0009 0000 0000 C. 

005D4620 0000 OOFF 0000 0000 0000 0000 0000 0000 . 

00504630 0000 0000 0000 0000 0000 0000 FFF3 OiOi .''O** 

005D4640 0100 0071 0EE4 0071 DE38 0071 UE/8 0000 • • •qmo*qfi8«c|nx* • 

005D4650 2DC4 0000 0000 00/1 UE5C 0041 0000 0000 -/.qil\»A**** 


While disfilaying the same memory’ with the WindowKecord 
template produces: 


dm @windowllsL WiitdowRvc-urd 


Displaying WindowRorord nt 005D45D0 


0O5D45E0 portRcrT 
005n45F.8 visRgn 
005D45EC clipRgn 
005D463C windowKind 
005l)463E visible 
005D463F hililed 


#0 00 #148 #104 (v #104. h #148) 
007D5DD8 •> #0 #0 #148 #104 [non-reetj 
00002UBC -> [wide-open region] 

FFF3 

true 

true 


005D4640 goAwayFlag 
005D4641 sparoFlng 
005D4642 .strnrRgn 
00504646 contRgn 
0050464A updateRgn 


true 

fal.se 

007inEE4 -> #13 #87 #181 #193 [non-rect] 
0071DE38 •> #32 #188 #180 #192 [non-reetJ 
007iDE78 •> [empty] 


005D464E windowDef Proc 00002DC4 -> 008D9C00 -> 
005U4652 dataHandle NIL 


005D4656 LUleHandie 0071DE5C > 0O8DAOE0 > “Calculator” 

005D465A LlLloWidLh 0041 

005D465C controlLisr NTT. 

00504660 nexrWindow NIL 

00504664 windowPlc NIL 

00504668 refCon 00000000 


In.stead of 136 bytes of hex spewed onto the screen, you get 
a fairly nice l(K)king description of the window in the form of a 
WindowKecord .structure. An added bonus of displaying 
memory via a template: a template definition can contain certain 
types which MaesHug knows are referred to by pointers in the 
memory being displayed. Wlien MaesRug displays rhe.se 
elements, it follows the addres.ses to the data of interest, and 
displays /ba/ in a readable format. Great examples in the listing 
above are the “visRgn” and “titleHandle” fields. 


Roll Your Own DLiUKKiER 

Obviou.sly the power of extensibility is most appreciated 
when you have occasion to require a custom addition to the 
built-in functionality of MaesRug. Some MaesRug 
enhancements can be found in the [)ublic domain, or in 
friends’ private collections, 'rhe.se enhancements are easily 
installed by dragging the re.source files in which they were 
delivered into a folder called “MaesRug Preferences” inside 
your Preferences folder. MaesRug will retrieve the re.sources 
from all such re.source files when it initializes itself early in 
the boot process. You could also u.se KesFdii lo copy and 
paste the re.sources into MaesRug it.self, but by leaving them 
outside of MaesRug, you can easily keep the enhancements 
when you update to future relea.ses of .MaesRug. 

If you can’t find the enhancements you need on the 
Inlernet or from your geeky friends, you will have to resort to 
writing your own. Fortunately, writing templates and macros 
is very simple, and progranmiing demds takes only a bit more 
effort. 'lb get started on templates and macros, open up 
MaesRug with Re.sFdit and look at some of the built in 
examples. You can copy the ‘TMPL’ resourc’es from MaesRug 
to your own resource file, which will allow you to edit macros 
and templates with ResFdit’s template (not to be confused 
with MaesRug templates) editor. A .sam[)le dernd project is 
included in both CodeWarrior and MPW format in the 
MaesRug relea.se archive. Once you’ve learned to concoct your 
own MaesRug enhancements, you will be free to dream up 
completely new’ ways of solving your debugging problems. 

Part Three: Ma(.sBu(; Enters the Mii leivnrim 

Now it is 1999, and the MaesRug available on Ap[)le’.s web 
site is much different than the MaesRug first rolled off the line in 
1981. Here are .some of the features of MaesRug that might 
surprise you if you haven’t been i)aying attention to the most 
recent MaesRug releases. 


Debugger Commands 

“Debugger commands”, or demds, are independent pieces 
of code which MaesRug allows you to execute from the 
command line while you are debugging. These commands, 
packaged in ‘dernd’ resources, are the most significant 
contributors to MaesRug’s extensibility. There are limitations to 
the types of cxxle that demds can execute, and output is 
re.stricied lo text displayed via MaesRug’s text screen, but for 
mo.st of your specialized debugging needs, the facilities of the 
dernd architecture will be perfect. Like macros and templates, 
much of the lx.‘havior taken as “built-in” to MaesRug is actually 
implemented in the various demds that come pre-installed with 
MaesRug. 'lb get a li.st of the demds available to you from 


Mouse Support 

MaesRug supports simple operations involving the 
MoiLse. Yes, break into MaesRug and move the mouse 
around. It’s not a bug — click on .some items in Mac.sRug’s 
display to get a feel for the effects. Mouse support is handy 
when you don’t want to retype an address that is already 
displayed on the .screen into a MaesRug command 
expression. Another popular use is for changing the height 
of the PC section of MaesRug’s display — ju.st click and drag! 

CFM Symbol Execution 

How many times have you wanted to execute a 
particular Mac O.S API call from within MaesRug, but you 
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didn’t have a dcmd to do it for you? If you arc an especially 
adept MacsBug user, you might have done this in the past by 
extreme MacsBug direct manipulation. You would write 
down or save in macros the contents of the registers, switch 
the PC to a free spot in memory, type out the hexadecimal 
code that prepares the stack and calls an A-Trap, and trace 
over the A-'l'rap before finally restoring the state of registers, 
the PC, and the stack to their original values. 

Thankfully, MacsBug now possesses an amazing 
functionality that obviates the need for this kind of hacking. 
You can ask MacsBug to execute any routine that is exported 
by a CFM library, directly from the MacsBug command line. 
Since almOvSt every Mac OS APT routine is exported through 
some library (even if it’s only glue code to get to the 68K 
implementation), you have access to almost any Mac OS API 
call that could assist in debugging your code! To execute an 
exported routine in MacsBug, simply preface the routine 
name with the © symbol (option-G), put the parameter list in 
parentheses as you would in a C function call, and press 
return. The return value of the function is the MacsBug 
expression value returned by the command. For example, if 
you type the MacsBug command: 

€)MovGWindow(@WindowList, //lOO, #100. 0) 

The window that is front-most in the current application 
is moved to location (100, 100) on the screen, and MacsBug 
returns the following output: 

©MoveWindow(@09L)6. #100, #200. 0) = $OOOOOOFF #255 #255 

The value of the expression in this case should be 
ignored, because MoveWindow does not have a defined 
return value. Another simple example: 

©HMCetBalloons() 

Causes MacsBug to reuirn the following output: 

©HMGetBalloonsO = $00000000 #0 #0 

Which tells me that Balloon Help is currently inactive. 
Clearly, there is enormous potential for this feature, and you 
will only know how handy it is when you remember that it’s 
there in the midst of a really tough bug. 

The feature does have some drawbacks, of course. First, 
you must phrase all of the parameters to the routine as 
explicit values. MacsBug doesn’t know how to translate the 
text “true” into a valid numeric value for the function you are 
calling. Second, if any of parameters are pointers that receive 
an output value (VAR parameters), you are responsible for 
pa.ssing an address to a legitimate memory location. I am in 
the habit of using playmem for such things. For example: 

©CetindStringCplayraeni. #128. 1) 


Which gets the first string from ‘S'l’K#’ resource 128 and 
copies the string to the “play” memory reserved by MacsBug. 
You can now display the contents of the string by typing “dm 
playmem”. Last, and most importantly, MacsBug will not 
police the safety of the CFM call you are making! Calling 
routines at certain times and with certain parameters may 
spell death for your debugging session. Among the factors to 
consider are: the internipt level, the reentrancy of code that 
is currently being executed, and the state of the file system 
if the routine you’re calling will access files. In general, this 
feature falls into the “desperate actions” category, but as you 
come to depend on it, you may enjoy being desperate! 

PowerPC Watch Points 

A number of MacsBug’s features evolved during the years 
when Macintosh computers ran solely on Motorola’s 680x0 
series of CPU. Since the introduction of the PowerPC based 
Macintoshes, MacsBug has continued to evolve, albeit 
sometimes slowly, implementing functionality for PowerPC that 
matches what we grew accustomed to on 680x0 computers. 

One very useftil feature for 680x0 code is called “step 
spying”, and it can still be activated by using the “ss” 
command. Basically, what step spying does is to execute 
instructions one at a time, checking at each step whether a 
particular range of memory was written to. This is very useful 
when you have found a bug that is caused by the wrong data 
being written to a location in memory, and you want to find 
the culprit. You .set a step spy on the address, wait for the 
computer to sluggishly execute instructions one by one, and 
hopefully when you break into MacsBug again, you are 
.staring at the code that writes the bad value to that address. 

Since step spying is implemented by stepping, 
in.struction by instruction, through 680x0 code, it is 
completely useless when the offending code is in PowerPC 
format. MacsBug users who have needed step spy style 
functionality for PowerPC code have been essentially out of 
luck for quite some time. Steadily, however, a new 
functionality in .MacsBug called “watch points” has been 
developing. With release 6.5.4a6 of MacsBug, this 
functionality has become remarkably more functional and 
sub.stantially less likely to crash your machine. 

To set a watch point in MacsBug, type “wp” followed by 
one or two addresses. If you specify one address, MacsBug 
will watch the 4 bytes at that location. If you specify two 
addresses, the range of memory bounded by the two 
addresses will be watched. Watch points are implemented by 
using the memory protection feature of the PowerPC 
proce.ssor. When you specify a watch point, the memory 
pages that contain the given range are write protected. When 
some piece of code tries to write to one of the protected 
pages, MacsBug’s exception handler is called, which triggers 
a break into MacsBug if the attempted write was in the 
desired range. Watch points stay in effect until you clear 
them by using the “wpc” command. 
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The walcli points functionality is in its infancy. There are 
a number of limitations that are described in the release 
notes: 

• To use the watch points functionality, you must install the 
Emulator Update file from MacsBug’s distribution archive into 
your System Folder. 

• The emulator update only works on Power Mac 9500 and 
newer machines. 

• No more lhan one watch point can be set at a time. 

• When a watch |:)oint is hit, you may not safely trace or step 
until clearing the watch point. 

• Wiitch points can not be set on memory locations on the 
stack, memory that will be addressed with an atomic 
instruction (“Iwarx” or “.stwcx”), or the memory location z.ero. 

The limitations are significant, but those of you who have 
Ix^en waiting patiently for a successor to .step spying will Ixt able 
to look past them and apprec:iate the mere existence of this 
feature. I can see your head nodding along right now, “I don’t 
care if it’s buggy, I need that feature!” Well, there you have it. 

Summary 

MacsBug is a veiy powerful debugger. If you didn’t believe 
so before reading this article, T hope you will now agree, and I 
hope you will find occasion to make use of its power in your 


own debugging pursuits. For those of you who didn’t need to 
lx: convinced, I hope that the new features will refocus your 
attention on the intrepid debugger that, tc.^ this ckiy, is critical to 
Mac OS development everywhere. Remember, the most 
powerful way to grow the functionality and evolve this debugger 
into the next century is by writing and distributing your own 
demds, macros, and templates to the Mac OS developer 
community. MacsBug’s evolution is not controlled by one 
persc^n, one company, or one countiy — it’s up to you to 
continue improvising and revolutionizing the functionality of a 
veiy simple, very complicated development t(X)l. 

Suggested Readinc. 

The following are gocxi references for [hose of you who 
need a more detailed review of MacsBug’s functionality. 

Apple Computer, MaesHng Reference and Debugging 
Guide, available online at 

<http://developer.apple.com/tools/debuggers/MacsBug/Documentation/ 

MacsBugRef_6.2.sit.hqx.> 

Othmer, Kon.stantin and Jim Straus. IX^hugging Macintosh 
soflivare iiith MaasBug, Addison Wesley Publishing Company, Inc. 
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Fast Blit Strategies: 

A Mac Programmer’s Guide 


Getting better video 
performance out of the 
Mac isn’t hard to do — if 
you follow a few rules 


CListornizc QuickDraw wiliioiiL patching any traps (among other 
subjects). In order to keep the i:>ace brisk, well assume that you 
already Imow what a GWorld is, how to manipulate PixMaps, and 
the basics of display modes. If you need to bmsh up on these items, 
a good crash course can be found in Dave Mark’s Mac Programming 
/vlQ^book (IDG Books, 1996). 


Introduction 

Ironically, the main performance 
bottleneck for game programmers today — 
as ten years ago — is getting pixels up on 
the screen. With the advent of 100 MHz bus 
speeds, built-in hardware support for 
2D/3D graphics acceleration, megabyte¬ 
sized backside caches, and superior 
floating-point performance, you’d think 
screen refresh rates would no longer be an 
issue. But as CPU and bus speeds have 
increased, so has monitor resolution — and 
pixel throughput. Providing the user with 
cinematic animation at full screen 
resolution remains a formidable challenge. 

Because of human interface concerns, 
writing direct-to-screen has always been 
treated as something of a talxx) in the Mac 
world. QuickDraw was invented to .save us 
from having to resoit to such low-level 
techniques. But there are still times when 
writing directly to video memory makes 
sense, paiticulaiiy in game programming, 
where anything goes when it comes to user 
interface design. In this article, we won’t shy 
away from direct-device writing or treat it as 
a taboo subject; in fact, we’ll concentrate on 
it, with a view toward optimizing our code 
for tlie G3 (and soon, CA) chip architeclure. 
We’ll talk about assembly language, cache 
issues, line-skip blitting, and how to 


Snappy Screen Drawing 

First, let’s summarize the basics. (If any of the following sounds 
unfamiliar, you should probably read up on video device 
fundamentals.) It should go without saying that maximizing screen 
drawing performance usually means taking advantage of one or 
more — or po.ssibly all — of the following techniques: 

• Use 8-bit color instead of 32-bit (which cuts bus traffic by 75%). 

• Cache and redraw dirly reels only (so you don’t repaint 
more territory than necessary). In games where most of the 
screen’s pixels don’t change from frame to frame, it pays to 
just keep trac k of the regions that need redrawing, and only 
redraw those regions. 

• Use pixel-skip draw techniques. TIus means implementing your 
sprite-drawing in such a way as to draw only tlie non-empty 
pixels in a sprite, skipping over “underlay” areas. But instead of 
in.specting values in a mask, you can get extra performance by 
implementing a “run length” af)f)R)ach wherein runs of visible 
sprite bytes are packed together. Tlie idea is to insiiect the run- 
length byte (like tlie first liyte of a Pascal string) and draw that 
many bytes; then inspect the skip-length byte of the next (empty) 
am, and skip over that many bytes; and so on. If you can just 
inspect length bytes rather than mask bytes, you can save cycles. 

• Use line-skip draw routines. Simply put, this means drawing 
every other line of the image, the way an interlaced N18C 
television picture is drawn. By simply omitting half the drawn 
data, you cut the redraw time in half. (The u.ser .sec^s a dithemd 
image.) If the blit area is small enough, you may be able to write 
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directly to the screen (wiihoui tearing or (lasliing) at vertical 
retrace time, instead of writing to a back buffer. (When you write 
to a back buffer, of course, you’re writing everything twic:e: once 
to the buffer, once to the sc:reen.) 

• Draw 64 bits at a time — or however many bits the 
architecture will support. Someday there will doubtless l)e a 
128-bit “long double” or “double double,” tlie way there is now 
a 64-bit “long long.” (If you don't know about long longs, 
consult your compiler documentation.) Until then, for best 
performance, you should always copy data to tire screen as 
64-bit doubles — never as anything shorter. Ail PPC chips 
have thirty-two floating-point registers and all can load a 64- 
bit double in one CPU cycle, so it makes sense to lake 
advantage of the throughput potential that the architecture 
offers. Anything less represents wasted cycles. 

• Observe proper data boundary alignment. (Write to and from 
addresses that are evenly divisible by 4, 8, or l6 — whatever 
is appropriate to the architecture and the drawing mode.) 
Also try to make all window and sprite dimensions a multiple 
of 16 or 32. Most graphics accelerator boards are designed to 
deliver their best performance when this is the c*ase. 

• Access data linearly (by incrementing pointers); avoid 
pointer arithmetic involving multiplications. Some 
applications even go so far as to maintain tables of line-start 
addresses, so that pointer addresses can be accessed via table 
lookup instead of calculated on the fly. (Depending on the 
chip architecture and cache performance, this tactic will 
either work like a charm or generate pipeline stalls.) 


• Use wide, shallow graphic elements in preference to tall, 
narrow ones. (There are more raster lines, and therefore 
more pointer arithmetic, in tall graphics.) 

• Implement your own custom drawing routines where 
appropriate, including, possibly, a replacement for CopyBits(). 

Getting the Most out of CopyBits 

The Mac’s main general-pur|X)se blit utility is, of course, 
QuickDraw’s venerable CopyBits() routine. Because .so many OS 
and user processes rely so heavily on it, and because tlie entire 
Mac user experience hinges on its performance, CopyBits() has 
lK‘en very higlily optimized. The bottom line is that CopyBits() 
gives very good performance and is actually quite hard to 
improve upon, if it’s used properly. 

To get the best performance from CopyBits(), you have to 
observe a few ironclad rules: 

First, make sure the .source and destination rectangles are 
exactly the same dimensions. One of the cajxibilities CopyBits() was 
designed to offer is dynamic image resizing with dithering and 
antialiasing. (Ihis can actually be a very handy thing, in situations 
where you care more alx7ul antialiasing tlian speed.) If you provide 
source and destination Rects that are different sizes, CopyBits() 
stretches or shrinks the output accordingly and antialiases tlie result. 
Rut this means taking a major speed hit. So if |)erfomiance Ls 
critical, don ’/ make QuickDraw “dither down” your image. 

Secondly, use a nil maskRgn. Again, one of the general- 
purpose capabilities of CopyBits() is to allow on-the-fly masking 
of image areas. But this, too, exacts a speed penalty. If you must 
do masking via QuickDraw, use CopyMask(); don’t pass a 
maskRgn to CopyBits(). You’ll find that CopyMask() does much 
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faster masked blits. ('Irivia note: Don’t forget that CopyMask is 
one of a handful of QuickDraw calls that cannot be “recorded” 
between calls to OpenPicture and ClosePicture. If you need to 
make a PICT, use CopyBits.) 

Thirdly, lx: sure source and destination PixMaps are 32-bit (or 
lx:tter yet, 64-bit) aligned. They should also have the same pixel 
depth (same color mode). And your transfer mode should lx: 
sreCopy, which is a direct load-and-store mode, as opposed to the 
arithmetic modes that allow various types of pixel blending. 

Finally, be certain that the color tables are the same for the 
source and destination PixMaps. CopyBits() always examines the 
ctSeed field of the source and destination color tables to see if 
they differ (in which case color-table mediation will be called 
for). For best performance, coerce the ctSeed field of the source 
and destination color tables to the same value, with the 
following ghastly but e,s.sential C expression: 

(*( (*(srePixMap) )*>pmTable) )DetSeed = 

(*( (*( (*aGDevice)->^dPMap) )->pmTablG) ) >cLSeed; 

Kememlx:r that CopyBits() always checks these two seed 
values. If they are not the same, QuickDraw will waste time 
translating color table info, which you don't want. 

If you observe the foregoing niles, you will find that CopyBits() 
is (jiiile hard to improve upon as a general blit routine. Hard, but 
not imix)ssible. It turns out that if you write direc'tly to the screen 
yourself, bypassing CopyBits(), you can sometimes achieve a 5% to 
10% speed gain — but only if you ignore color tables, write 8-byte 
doubles, stay on fx'opeiiy aligned addresses, and keep source and 
destination lectangles the same size (with the width a multiple of 
8). In other words, you have to make your ccxle a gcxxl deal less 
general than CopyBits(). 


DlRliCl-rO-VlDEO 

Writing direct-to-.screen on the Mac is not difficult. First you 
have to get the .starting address of video memory, which can lx* 
done as follows: 

PixMapHandle pmh; 

Ptr videoMemoryAddr; 

GDHandle mainDevice; 

mainDovico ^ GclMairiDevice0 : 
pmh = (••mainDevice).gdPMap: 
videoMemoryAddr =■ GetPixBaseAddr( pmh ); 

'fhe Mac’s screen is just a glorified PixMap, and a handle to 
this PixMap is contained in the the GDevice record of each 
display device (and in the Graf Port record of every open 
window, incidentally). For safety, use the MacOS function 
GetPixBaseAddrO to get the base address. 

Next, figure out the offset from the top left corner of the 
screen to the lop left corner of the area you want to begin 
writing to. Multiply the raster-line start position (the global ‘y’ 
c(K)rdinate) by the screen’s rowBytes value; then, to offset 
horizontally, add the desired horizontal start position 
multiplied by the pixel size (which will be one byte for 8-bit 
color, two for 16-bit color, and four for 32-bit color; but the 


pixelSize field of the PixMap gives the size in hits, not bytes, so 
divide by 8). Let’s say you want to write to a starting position 
(in global coords) of 164, 1001, which is to say 64 pixels from 
the left edge of the screen and 100 pixels down from the top. 
For this, you would do: 

long horizOffsGt = 64, verticalOffset = 100; 

Ptr writeAddr; 

wrileAddr = videoMemoryAddr; // obtain screen origin address as shown above 
writeAddr += verticaiOffset ‘ ((**pmh).rowBytes & OxBFFF); 
writeAddr += horizOffset * ((**pmh).pixelSize/8); 

// Note: PixelSize is in bits, not bytes. Divide by 8 to convert to bytes. 


The rowBytes value tells you the number of bytes in one 
complete raster line, including any padding that QuickDraw 
might need for data alignment. The mask operation involving 
OxSFFF requires a bit of explanation, if you’re new to Mac 
programming. The first two bits of rowBytes are reserved for 
System use. The MacOS inspects the.se bit values to determine 
whether the pixel data are in the form of a black-and-white 
BitMap, or a tnie (color) PixMap. Cl'his is an early Color 
QuickDraw hack, needed in order for PixMaps and BitMaps to be 
used interchangeably in Color QD routines. When the original 
Bc'iW QuickDraw was first written, there were only BitMaps.) 
The important point is, don’t forget to mask rowBytes against the 
hex value OxSFFF in order to determine the true number of bytes 
in a ra.ster line. If you fail to do this, you’ll get strange bugs, 
becau.se the raw value of rowBytes will usually be negative 
(rowBytes is a signed short int). 

Once you’ve calculated a start address, you can write to it — 
preferably 64 bits at a time. Determine how many pixels’ woitli of 
data you’ll need to write, horizontally, then l(X)p through raster 
lines, writing ()4 bits at a time, as shown in Listing 1. 


Listing 1: FastBlit( ) 


l-asiBliiQ 

Note: On entry, this hinction expects source aiuJ destination pointers to be precalculated 
(to reflea the locations of the up|XT left comers of die source and destination “\\Titc” 
aa-as); no |iointcr arithmetic is done iaside this function. Al.so note that the blit area’s 
width (in liytes) must be evenly divi.sible by 8 — a concession to .speed. 


void FastBlit(long depth, long doublc.9Wide, 

Ptr GWorldAddr, Ptr scrconAddr, 

long offRowByLes, long screenRowBytes ) 

( 

double *dst = (double •) screenAddr: 
double *src = (double *) GWorldAddr: 
long doublesAcross; 
long screenSkip, offscreenSkip: 


screenSkip = screenRowByLes/8 doublesWide: 
offscrcenSkip = offRowBytes/8 - doublesWide; 


do I 

doublesAcross = doublesWide; 
do I 

•dstl-I = *src-H-; 

I while ( doublesAcross) : 


sre += offscreenSkip: 
dst += screenSkip: 


) while ( - depth); 

1 


In this scenario, GWorldAddr is the source address for an 
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offscreen GWorld. There is no need to make local copies of the 
input parameters, since the compiler will [yass the values in 
registers (assuming you’re compiling to a PPG target, that is). We 
set up do while (rather than for or while) loops to achieve smaller, 
tighter exec utable code; and we cast our .source and destination 
pointers to pointers-to-douhle so that we axn write 64 bits at a 
Lime. We also take care to access data linearly, eliminating 
multiplications from our pointer arithmetic. Result: The code 
shown alx)ve is 5% to 10% fa.ster than CopyBits(), depending on 
monitor mode and image dimensions. That’s not much of a sjx?ed 
improvement, admittedly, but if you need it, it’s there. 

Optimizinc; Bui Code for PPC 

If you grew up writing code for CISC chips, it might seem 
as though the code in Listing 1 could be optimized a bit further. 
First, why not declare all local variables as regi.ster variables? 
Secondly, why not unroll the inner loop? For that matter, why 
not write the whole thing in assembly language? 

The reason we don’t declare any register variables in our 
blit routine is that the compiler already knows to put everything 
in registers. (If you don’t believe it, do an assembly dump.) 
Using the “register" keyword gets us no additional speed 
because on the PowerPC, almost everything is done in registers 
by default. Recall that the PPC chips all have 32 general-purpo.se 
32-bit registers and another 32 “wide" (64-bit) floating-f)oint 
registers. The first 8 integer registers and 13 floating-point 


registers are available for argument-passing, and most compilers 
will pass ftinction [)arameters in these registers rather than on 
the stac:k. Likewise, if there are less than 224 bytes of local 
variables inside a function, the compiler will tiy to put all local 
variables in registers. The stack is avoided at all costs, because 
it means going out to the data bus, which on many computers 
runs at only 25% of the CPU .speed. 

The fastest way for code to execute is for all data and all 
code to .stay inside the CPU at all times, where things happen at 
clock speed. Toward this goal, the designeis of the G3 (PPC 750 
scries) chips put 32K of data cache and 32K of instruction cache 
on board the chip itself, so that the most recently used code and 
cLita can lx* accessed at clock speed. Of course, 32K isn’t big 
enough to hold all your code or all your data, whic:h is why the 
chip designers put a generous secondary cache (typically 512K 
or 1Mb) on the back side of the chip — the so-called “backside” 
cache. This cache is big enough to hold quite a bit of data — 
even some entire images — but to access it requires that you 
step down to one-half CPU clock speed. That’s a big speed hit, 
but it’s still not as bad as having to go out to DRAM via the main 
bus. On mo.st Macs these days, the Ixis nins at either 66 MHz or 
100 MHz. If your CPU is constantly requesting data from RAM, 
your computer is essentially running at 66 or 100 Mhz, not the 
300 or 400 MHz. that the CPU may theoretically lx capable of. 

What it means is that you should group your main 
perfonnance routines together, .so that they stay in the cache; avoid 
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sialic variables that require frequent trips to the bus; and be careful 
about unrolling l(K)ps. If you unroll a loop too far, it could fall out 
of the cache — in which case, you just scored a 50% speed hit. 

Incidentally, if you want your routines to be close to each 
otlier in tlie cache, group them togetlier sequentially in your C 
source. The Metrowerks compiler puts executables together in the 
order you write them. There is no need to use the segment pragma; 
in fact, that pragma only works when compiling to a 68K target. 

Pipelining 

Another important consideration on PPG targets is 
pipelining. The processing units of the G3 chips have separate 
facilities for fetching, deccxling, and executing instructions. 
These facilities are designed to operate concurrently, which is to 
say that while one instruction is executing, the next one is being 
fetched and another one is Ixring decoded — under ideal 
circumstances. When data and code can be fetched directly from 
the chip’s onboard (32K) cache areas, circumstances are pretty 
close to ideal and the PPG pipeline can prcx:ess one instruction 
per ckx'k cycle. But when data has to be fetched from RAM via 
the bus, everything screetches to a halt as the GPU waits for data 
to arrive. This is called a pipeline stall. 

A good compiler will analyze your code and anticipate 
po.ssible pipeline stalls, then try to interleave or reorder 
instructions as needed to give the GPU something to do while 
data is being retrieved. Bui you can easily thwart the compiler’s 
be.st efforts by, for example, insi.sting on putting one load/store 
ojxration after another after another in your code — i.e., by 
unrolling a dala-copy loop. 

Take our blit routine, for example. An assembly dump of 
the main loop from Listing 1 is shown in Listing 2. (For clarity, 
we’ve omitted half a dozen lines of setup code.) Note first of all 
that the assembly language for our nested double loop is only 
eleven lines long, which is not bad. (We save a few lines by 
using the do while construct in [)lace of a for loop.) The first line 
is a register-move (mr) that loads our inner-loop counter 
variable into r8. The second line is a load-floating-double (ltd) 
instruction using the (source) address .stored in r5. But notice 
one thing: The “write” (or .store-floating-double: stfd) instruction 
doesn’t occur until three lines later. In between the load and 
store instructions are an add-immediate (addi) and a sulnract- 
immediate-with-carry (subic) operation. The add operation 
corresponds, of course, to a pointer post-increment in G, while 
the subtract-with-carry is a decrement of our loop counter. After 
the store operation comes another pointer post-increment 
(notice that the address is increased by 8, because we’re 
operating on doubles), then the branch-if-not-equal instruction. 

What’s happened here is that the compiler has decided 
(quite correctly) that while the load instruction is executing, 
the processor might just as well do some pointer and loop- 
counter arithmetic before executing the store instruction, 
because the load will take a while (requiring a RAM access — 
or perhaps a backside-cache access). Since the chip has 
separate load/store and processing units, these operations can 


occur concurrently. In other words, the intervening arithmetic 
operations between the read (load) and write (store) cost us 
nothing. Meanwhile, tlie chip’s branch unit has been watching 
the “carry bit” that was (or wasn’t) set during the loop-counter 
decrement (the subic instniction), so that by the time we get to 
the branch point, the chip’s branch unit already “knows” where 
to take us next. Thus, the branch costs us nothing. (On the PPG 
750, the branch unit operates concurrently with procejising 
units.) d'his is a good example of how instruction interleaving 
can be exploited for maximum performance on a PPG host. 
I'here are no pipeline stalls, because processing continues 
even while a RAM access is taking place. 


Listin g 2; Fa s tBlit C ) Disassembled_ _ 

FablBlil.aMn 

Note: This is PPC assembly code generated by Metrowerks compiler. Comments by the 
author. (See article text for discussion.) 


00000020 

mr 

r8.r4 

00000024 

Ifd 

fp0.0(r3) 

00000028 

addi 

rS.rS.S 

0000002C 

subic. 

r8.r8.1 

00000030 

stfd 

fp0.0(r6) 

00000034 

addi 

r6.r6,8 

00000038 

bne 

*-20 ; 

0000003C 

add 

r.S.rS.r? 

00000040 

add 

r6. r6.rO 

00000044 

subic. 

r3,r3.1 

00000048 

bne 

* 40 : 


loop counter setup 
: read from input 
; sre pointer post - increment 
: decrement loop counter 
; write output 

; dst pointer post-increment 
loop condition test 
; pointer offset arithmetic 
; pointer offset arithmetic 
: decrement loop counter 
loop condition lest 


Now let’s consider what happens when we try to unroll 
the loop. Take a look at Listing 3, which is an assembly 
dump of a version of Listing 1 in which the inner loop has 
been unrolled four limes. 

It may not seem like it at first, but this code is nowhere near 
as efficient as that of Listing 2. The reason is that the many close- 
together load/store operations are almost certain to generate 
pipeline stalls. A little profiling confirms that there is no speed 
gain from unrolling the loop. 


Listing 3: Unrolled Blit Disassembled _ 

UnrolledBIit.asm 

Notc:Tliis is PPC assembly code generated by Metrowerks compiler. See article text for 
discussion. 


00000018 

mr 

r0.r4 

OOOOOOIC 

Ifd 

fp0.0(r5) 

00000020 

addi 

r5.r5.8 

00000024 

stfd 

fp0.0(r6) 

00000028 

addi 

r6.r6.8 

0000002C 

Ifd 

fp0.0(r5) 

00000030 

addi 

r5.r5,8 

00000034 

stfd 

fp0.0(r6) 

00000038 

addi 

r6.r6.8 

0000003C 

Ifd 

fp0,0(r5) 

00000040 

addi 

r5.r5.8 

00000044 

stfd 

fp0,0(r6) 

00000048 

addi 

r6,r6,8 

0000004C 

Ifd 

fp0.0(r5) 

00000050 

addi 

r5.r5.8 

00000054 

stfd 

fp0.0(r6) 

00000058 

addi 

r6.r6.8 

0000005C 

subic. 

rO.rO.l 

00000060 

bne 

*-68 

00000064 

slwi 

r0.r7.3 

00000068 

add 

r5.r5.r0 

0000006C 

slwi 

r0.r8.3 

00000070 

add 

r6.r6.r0 

00000074 

subic. 

r3.r3,l 

00000078 

bne 

*-96 


read 
; bump 

write (stall) 
; bump 

read (stall) 

; bump 

write (stall) 
; bump 

read (stall) 

: bump 

write (stall) 
; bump 

read (stall) 

; bump 

write (stall) 
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Customizing QuickDraw 

Most of the lime, you’ll be hard pressed lo heat CopyBits(). 
But if you do manage to Ix^at CopyBits(), you can (and should) 
consider installing your own blit routine as a QuickDraw 
bottleneck proc, replacing CopyBits(). Maybe you didn’t know it, 
but (QuickDraw is extensible (thanks lo some nice design work, 
circa 1983, by Bill Atkinson). There are 13 low-level “bottleneck” 
functions that QuickDraw uses to do things like draw lines, 
rectangles, ovals, etc. (See Table 1.) One of the standard 
bottleneck f)rimitives is called StdBits(). This is the low-level blit 
function that CopyBits() ultimately vectors to. You can install your 
own replacement function here, and QuickDraw will 
automatically vector to it when your program needs to call on 
CopyBits(). This is similar to patching a trap, except that Aj)|)le 
(or Atkinson) designed the QD bottleneck junij) table to be 
wholesale-replaceable on a window-by-window basis. By 
“wholesale-replaceable,” we mean that the entire jump table 
(containing addre.s.st?s for all of the QD drawing primitives) can 
and indeed miisl l)e replaced at once. The relevant data stnicture 
is (he CQDProcs .struct (see Listing 4). 


TABLE 1: QuickDraw Bottleneck Proc Prototypes 

pascal void SldToxt(short byteCount, I’lr tcxtBuf, Point 

nuraer. Point doiioin); 

pascal void StdLlnc(Point newPt); 

pascal void StdRect(GrafVcrb verb, const Rect *r); 

pascal void StdRRect{GrafVerb verb, const Rect *r, short 

ovalWidth, short ovalHeight); 

pascal void StdOvaKGrafVerb verb, con.st Rect *r); 
pascal void SrdArc(GrafVerb verb, const Rect *r, short 
startAnglc, short arcAngle); 

pascal void StdPoly(GrafVerb verb. Polyllandlc poly); 
pascal void StdKgn(GrafVerb verb, RgnHandle rgn); 
pascal void StdBits(const RitMap *srcBits. const Rcct 
*srcRect, const Rect ‘dstRecl, .short mode, RgnHandle 
maskRgn); 

pascal void Std Comment (short kind, short. dataSize, Handle 
datallandlc) ; 

pascal short StdTxMeas(short byteCount. const void 
*textAddr. Point •nuraer. Point •denora. I'ontlnfo *info); 
pascal void StdCetPic(void *dataPtr, short byteCount); 
pa.scal void StdPutPic(const void *dataPtr. short 
byteCount); 
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In.stalling a cu.stom bottleneck proc is actually quite simple. 
Listing 5 shows how it’s done. The key is lo realize that et>ery 
ivindow has its own .set of bottleneck procs, accessible through 
the grafProcs field of tlie GrafPort structure. You replace the 
entire bottleneck jump table (containing pointers to all 13 low- 
level drawing functions) all at once, even if you only need to 
customize ju.st a single lK)iileneck procedure. When you no 
longer need your cu.stom bottlenecks, simply nil out the 
grafProcs field of the window’s GrafPort structure, and 
QuickDraw will know to revert to its own default proc' table. 


Listing 4; CQDProcs Data Structure 


.qt-ruct CQDProcs I 

QDTextlJPP 

QULIneUPP 

QDRecLUPP 

QDRRectUPP 

QDOvalUPP 

QDArcUPP 

QDPolyUPP 

QDRgnUPP 

QDRit.^UPP 

QDCommentlJPP 

QDTxMeasUPP 

QDCetPicUPP 

QDPutPicUPP 

QDOpcodeUPP 

UniversalProcPtr 

UniversalProcPtr 

UniversalProcPtr 

Univer.salProcPtr 

UniversalProePtr 

UniversalProcPtr 

I: 


iGxLProc; 
lineProc; 
rectProc: 
rRectProc; 
ovalProc: 
arcProc; 
polyProc; 
rgnProc; 
blIsProc; 
comment Proc.; 
txMeasProc; 
getPicProc; 
putPicProc; 
opcodeProc; 
newProcl; 
newProc2; 
ncwProc.3; 
newProcA; 
newProcS; 
newProcb; 

CQDProcsPtr; 


typedef struct CQDProcs CQDProcs, 


Listing 5: SetupCustomBottlcneckQ _ 

SciupCiistomBottleneckO 

A function to attach a new set of QuickDraw procs to a window. 

CQDProcs qdNewProcs; //globals 

void SetupCustoraRottleneck( CWindowPtr w) ( 

SetStdCProcs ( &qdNewProcs ); // fetch copy of default procs 

// Now replace CopyBits with our own cu.siom routine: 
qdNewProcs.bitsProc ^ NewQDBitsProc( CustomBlit ); 
w->graf Procs = &qdNewProcs; //install new procs 
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Listing^6: CustomBlitO _ 

(AistomBlitO 

WARNING: This is a cuslom routine that expects screen to be in 8-bit color mode; also, 
image must be 640x480. The.se numbers are hard-coded for .speed. This is NOT a general- 
purpose routine. Use with caution. 

void CufltomBlit(BitMap *srcBits, 

Rect *srcRect, 

Rect MstRect, 
short mode, 

RgnHandle regionH) 

{ 

^pragma unused (srcRect.dstRect.mode,regionH) 
double *dsL; 

double *src = (double *) srcBits >baseAddr; 

long rows; 

long yeaManyAcross; 

long sreSkip, dr,tSkip; 


//The following have ail been previously cached in globals; 
dst = gDestAddr; 
rows = gRows: 
sreSkip = gSreSkip; 
dstSkip = gDestSkip; 

//•***••••••• BEGIN BU r •*••••••*•• 

do I 

yeaManyAcross = 6^0/8; 
do ( 

*dstl+ = *SrG-H-; 

1 while ( - yeaManyAcross ); 

dst dstSkip: 
sre += sreSkip: 

I while ( - rows ): 

//****•••••* END Bl.IT •*•••**•••• 

1 

Listing 6 shows a custom blit routine, hard-coded as to 
window dimensions and bit depth, with certain key 
parameters pre-cached in globals. (With any luck, those 
values will stay in the data cache — or el.se the backside 
cache — for fast access when you most need them.) You can 
think of these globals as your very own “QuickDraw 
globals.” 

You may have noticed that the arguments to 
QuickDraw’s low-level grafProcs don't include a deslinalion 
address. That’s because the procs apply only to the current 
window (the current GrafPort). It’s assumed that you’re 
writing into the current port. Remember, at this low level, 
there’s no need to call SetPort()! 

Using hard-coded values in a low-level routine without 
error checking is obviously .somewhat dangerous, but it’s 
necessary if you want maximum speed. Plus, you have to 
remember that for greater flexibility, you can — and should — 
develop multiple custom-draw functions, tailored to various 
circumstances, .so that you can vector to the right one al the 
appropriate moment. Also, it’s good to know that QuickDraw 
will use your custom blitter only in the window you specify. 
(Again, every window or GrafPort has its own grafProcs.) Thus, 
if the user temporarily leaves your game in order to visit the 
Finder or another application, the other a[)plication(s) will .still 
draw correctly into their own windows. Likewise, if the user 
leaves the main gameplay window to look at a dialog window 


in your own program, the dialog will draw correctly, using 
QuickDraw’s default proc table. 

Bear in mind that you can replace any of the QuickDraw 
primitives you need to. For example, if your game could 
benefit from a special arc-drawing routine, you can install 
your own arcProc. If you’ve got something better or faster 
than the Bresenham algorithm, you can install your own 
ovalProc and/or lineProc, etc. 

One of the benefits of replacing QuickDraw’s grafProcs 
is that it lets you keep using native QD calls like LineTo and 
CopyBits in your code. This helps with code reusability as 
well as readability. After you’ve installed your own cu.stom 
blitter in place of CopyBits, you can just keep calling CopyBits 
throughout your code. If you come up with a better blitter 
later on, you can update your code just by changing one 
grafProc pointer. 

Extreme Measures 

If you’re looking for more than just a small incremental 
improvement over CopyBits (i.e., you want to be able to blit 
hundreds of 6'i0x'f80-or-larger frames per second), you’ll 
need to resort to extreme measures — such as (for example) 
line-skip drawing and/or pixel doubling. 

To implement line-skip drawing (interlacing), you can 
ju.st add a few lines of code to the custom blitter in Listing I: 

if (gPolarityH+ & IL = IL) 

I sre += offRowBy lgs/8: dst +“ screenRowRyies/8: 1 

screenSkip += screenRowBytGs/8; 

off.se reenSkip += of fRowBytfi.s/8; 

'I’hese lines should go immediately before the main 
(outer) loop. The .static or global variable gPolarity will keep 
an “odd-even” counter going, the idea being that on odd- 
numbered calls to the blitter, you’ll offset the source and 
de.stination pointers one raster line deep into the image. And 
evejy time the routine is called, you’ll calculate the “skip” 
values to include one extra raster line, so that you draw 
every' other line of the image. When you do this, of course, 
your redraw rate doubles, becau.se now you’re handling only 
half as many bytes of data. 

The interlaced redraw technique works very well for 
underlays and slow-moving objects, but as you can probably 
imagine, it will yield ghosting artifacts if the object that’s being 
drawn is moving across the .screen at an appreciable rate. 
(With a little ingenuity, you can probably think of 
workarounds for this — or maybe pul the effect to good u.se.) 

Another common speed-multiplying technique is pixel 
douhling, which is where each pixel of the .source image 
(whether it’s a sprite, icon, underlay image, or whatever) is 
drawn as a 2x2 tile on.screen. E.s.sentially, you’re .scaling a 
quarter-size image up to full size — hence, the potential 
exi.sts for a 4:1 speed boost. The downside to this technique 
is that it gives a “chunky pixel” look that can be annoying; 
but there happens lo be a useful workaround, in the form of 
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the ‘epx’ antialiasing technique pioneered by LucasArts’ Eric 
Johnston. Figure 1 shows how it works. 


Figure 1, The ‘epx* antialiasing algo nth m, 

(see text for discussion). 

The problem is this: how to scale pixel ‘P’ to be lour 
times its original size, but without all four new pixels 
necessarily being the same color. (We want some 
antialiasing.) Tn Figure 1, the tic-tac-toe grid on the left 
represents the pixel ‘P’ and its north, south, east, and west 
neighbors in the source (offscreen buffer) image. Tlie 2x2 tile 
on the right represents the new (onscreen) pixels, which will 
derive from P. The question is how to color PI, P2, P3, and 
P4 without giving the “chunky f)ixer’ look. 

The answer is to base PI on the back-buffer pixels ‘A’ 
and ‘C’; l)ase P2 on ‘A' and TV; base P3 on ‘C’ and ‘D’; and 
ba.se P4 on ‘D’ and ‘R’. We say that ‘A’ and ‘C’ are the 
“parents” of PI, ‘O’ and ‘B’ are the parents of P4, etc., and 
likewise, PI is die child of ‘A’ and ‘C’, and so forth. The rule 
to follow is this: If any two parents are equal in color, then 
make the child that color. Otherwise, let the cfiild be the 
color of ‘P’. Also, if at least three of the parents (A, B, C, D) 
are identical, do nothing: ju.st let PI = P2 = P3 = P4 = P. 
Qohnston discusses this technique on page 692 of Tricks of 
the Mac Game Programming Gums, Hayden Books, 1993.) 

The T‘px’ technique is not written in stone; you can and 
should experiment witli modifications to it, to suit your 
game's graphics. It’s more of an ad hoc heuristic than a 
theory-based algorithm. But it gives worthwhile results. Many 
sliipping games use this cheap, easy AA technique. 

Compressed Graphics 

An even more extreme way of speeding things up is to 
store your graphics in a highly compre.ssed state and 
decompress them to the screen at blit time. This is the basis 
of most “byte-packed” or “run length” sprite drawing 
techniques. It’s also how QuickTime gets much of its speed. 

Imagine, for a moment, that you could store all of your 
game’s static graphics (backgrounds, underlays, sprites of fixed 
dimensions, etc.) in 10:1 or 20:1 compressed form, in RAM; 
then, when you need to draw them, you send the compressed 
data over the bus to video memory, and have the image(s) 
decompress-to-screen with the aid of hardware support on the 
video board. This is exactly what happens on many accelerator 


boards that .support QuickTime, and according to Dispatch No. 
8 from the Ice Floe (Apple’s Quicktime tech notes, available 
online in the QuickTime area of Apple’s developer pages), you 
can take full advantage of this technicjue — hardware 
permitting — by simply using QuickTime’s Decompresslmage() 
call in place of CopyBits. Full details are available at 
<http://www.apple.com/quicktime/developers/icefloe/dispatch008.html>. 

Sprocketry 

If you’re serious about obtaining better screen-redraw 
performance — whether for a game or for any other purpose 
— you owe it to yourself to investigate Apple’s DrawSprocket 
library (.see http://developer.apple.com/games/sprockets). The 
DrawSprocket routines are extremely logical and easy to use, 
and they greatly simplify things like blanking and restoring 
the screen (including the desktop and menu bar), setting the 
color dej)th, implementing gamma fades, double and triple 
buffering, blitting at controlled cinematic rates, etc. Also, the 
DrawSprocket library takes advantage of hardware support 
for page-flipping when available. Sprocket blitting is so 
efficient, you probably won’t gain anything by installing a 
custom blit routine of your owm (unless you’re into extreme 
techniques), because the sprocket library will use a highly 
customized routine — customized for the exact graphic 
environment of your game. 

For a variety of reasons, you should make it a point to 
investigate the DrawSprocket library, which is the “drawing” 
portion of Apple’s Game Sprockets. (There are other sprockets 
for audio, networking, etc. — all of them royalty-free). 

Conclusion 

Although we didn’t have time to discuss it, many of the 
techni(|ues mentioned in this article are used in a small 
Metrowerks C code project called BlitsKrieg developed for 
this article and available online at <ftp://www.mactech.com>. Re 
forewarned that BlitsKrieg is simply a no-frills test program 
that draws a FICF to the screen numerous times, and reports 
the elapsed time in ticks. There is no event loop, no menu 
bar, etc. It’s strictly a quickie prototype for testing different 
blit techniques, but it does contain example code showing 
how to replace CopyBits with a custom routine, how to do 
interlaced blits, and how to call Quick'fime’s 
Decompressimage. U.se at your own risk. 

In conclusion. I’d like to reiterate a bit of advice once 
given to me by a mentor who was (and still is) a ninja-level 
ma.ster at making code go fast. His chief insight, which I have 
benefitted from many times, is that since the CPU can only 
execute a fixed number of instructions per second, and no 
more than that number, there is really no such thing as 
“making the machine go faster.” There is only sueh a thing as 
making the machine do less. 

To go faster, do less. Remember that, next rime you’re 
slamming dumptruck-loads of pixels to the screen. Mi 
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i PROGRAMMER'S 
CHALLENGE 


By Rob Boonstra, Westford, MA 


Tetraminx 

The last Challenge I entered as a contestant was the Rubik’s CuIk* 
Challenge, where entries had to solve a scrambled Rubik’s cul>e. 
While that Challenge was difneull enough to cause me to retire from 
competition after winning, I’ve sUiyed interested in puzzles. Some time 
ago I ran across Meffert’s World Of Puzzles, an online puzzle'vendor 
at <http://www.mefferts-puzzles.com/mefferts-pu 2 zles/catalog.html>, and 
ordered a few of their puzzles. The Tetraminx is perhaps the least 
difficult puzzle, much simpler than the Cu[)e, but still interesting 
enough that I thought it might make a good Challenge without driving 
any contestants into retirement. 

Tlie Tetraminx is formed by four hexagonal faces, each consisting 
of six triangles, joined in the shape of a tetrahedron, plus four triangles 
to complete the solid, as depicted at <http://www.mefferts- 
puzzles.com/pictures/tetramix.jpg.> 

Scrambled Tetraminx 



Your Challenge is to come up with a .sequence of moves that 
will return the puzzle to the goal state, where c^iich of the hexagonal 
faces consist of triangular facelets of a single color. 

The prototype for the code you should write is: 

//if defined (_cpiusplus) 

extern “C” I 
//end if 

typedef enura ( 

kYellow=^l .kBlue.kRed.kGreen 
) PiereColor; 

typedef enum ( 

kLeftCiockwise=l,kRightClockwise. 

kBottoinClockwi.se. kBackClockwise. 
kLeftCounterClockwise.kRightCounterClockwisc. 
kBottomCounterClockwise.kBackCounterClockwise 
) Move; 

typedef enum ( 

r single triangular faces named after the opposite hexagonal fate V 
kLeft,kRight.kBottom.kRack. 


/• edge faces named kXY, where X is the hexagonal face they are part of, 
and Y is the adjacent hexagonal face */ 
kBR.kRK.kKB, 
kLB.kBK.kKL, 
kKR.kRL.kLK, 
kLR.kRR.kBL. 

/* corner faces named cXY, where X Is the hexagonal face tlicy arc part of, 
and Y is the hexagonal face opposite the adjacent single triangle 7 
cRL.cKL.cBL, 
cLR.cBR,cKR, 
cRB.cLB.cKB, 
cLK.cRK.cBK 
1 PieceType; 

typedef struct ( 

PieceType piece: 

FieceColor color; 

1 FieceState: 

long r numberOfMoves V Tetraminx ( 

FieceState sLate[2Bj, /* initial .state of the 28 pieces 7 

Move moves [] , f* moves you generate 7 

long maxMoves /* maximum storage in move array 7 

): 

//if defined ( cpiusplus) 

1 

//end if 

The puzzle is manipulated with four [)air.s of 120-degree rotation 
moves that we will call kLeftXXX, kRightXXX, kBottomXXX, and 
kBackXXX, corres|X)nding to the four hexagonal faces of the 
Tclraminx. Tlie moves are named for the hexagonal face that remains 
fixed during die move.. Opposite each of those liexagonal faces are 
the single triangular faces whose positions remain fixed for all moves 
(except for rotation). E;ich move pair consists of a clockwise move and 
a counicTcltKikwi.se move, as viewed from the opposite single facelet, 
through the Tetraminx, al the face for which the move is named. 

The PieceType enum names the 28 triangular facelets. Facelets 
come in iliree types, and it is imixxlanl to understand the naming 
convention for llic faccleLs. The first type consists of the single 
triangular faces, and those are named kLeft, etc., for the move that 
rotates the piece, and for the opposite hexagonal face. The .second 
type is an “edge” facelet, one with a single adjoining triangle, and 
those are named kXY, where X (L, R, B, or K) is the hexagonal face 
containing the piece, and Y (also L, R, B, or K) contains the adjacent 
facelet. Finally, "corner” facelets have three adjacent triangles, two of 
them on the same hexagonal face, and one a single triangular face. 
Tlicse are named kXY, where X is the hexagon containing the piece, 
and Y is liie single triangular face. 

'fhis is probal)ly impossible to understand without a picture, so 
I’ve included one. A color version of the picture is available al 
<http://www.mefferts-puzzles.com/mefferts-puzzles/pictures/tetrmi5b.gif>. Tlie 
blue, red, yellow, and green faces are the left, right, lx)llom, and back 
faces, respectively. The face compri.sed of the single center (yellow) 
triangle is the kBack facelet. Starting wiili the blue triangle next to the 
kBack facelet, and moving clockwise around tlic blue face, are the 
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cLK, kLB, cLR, kLK, cLB, and kLR facelets. 

llie kBackClockwise move roiaics the yellow kBack facelet in a 
clockwise direction, moving the kLR piece (Blue-Red) to where the 
kRB piece (Red-Yellow) is, and the kRB piece to where the kBL piece 
(Yellow-Blue) is. 

If the nomenclature for facelets and moves seems confusing, the 
test code available via the Challenge mailing list will make it clearer. 
Alternatively, for those of you that are into group theory, the four 
clockwise moves perform the following permutations on the facelets: 


kRightCI(K:kwise: 
kLefiCKx'kwise; 
kBottomCloc'k wise; 
kBackCI(x*kwi.sc!; 


(kKL, kLl3, kl3K) (kLK, kBL, kKB) (cLR, cBR, cKR) 
(kRK, kKB, kBR) (kKR, kBK, kRB) (cRL, ('KL, cBI.) 
(kKR, kRL, kl.K) (kRK, kLR, kKL) (cRB, cLB, cKB) 
(kLR, kRB, kBL) (kRL, kBR, kLB) (cLK, cRK, cBK) 


I'etraminx FACELEI'S 



Your code should place the moves needed to solve the puzzle 
in moves and return the number of moves generated, or reRirn zero 
if you cannot solve the puzzle in maxMoves moves. 

Instructions for solving the Tetraminx are available at 
<http://www.mefferts-puzzles.com/mefferts-puzzles/tetrasol.html>. Since you 
pr()ba[)ly don’t have a Tetraminx handy, test code will be available 
to help you see the effects of the moves you make to solve the 
puzzle. The winner will be the solution that solves tlie puzzle in the 
fewest number of moves, with a 10% penalty added for each second 
of execution time. 

This will be a native PowerPC Challenge, using the latest 
CodeWarrior environment. Solutions may be coded in C, C++, or 
Pascal. 

Three Months Ago Winner 

Congratulations once again to Randy Boring for submitting the 
winning solution to the March Terrain Traversal Challenge. The 
March Challenge recjuired contestants to process sets of 3- 
diinensional input points, convert them into non-overlapping 
triangles, and then navigate across those triangles from pairs of 


starting poinLs and ending points. The score for a solution was based 
on the distance traveled, with a penalty for the change in elevation 
along each segment of the .solution, and an additional 10% penalty 
for each .second of execution time. The winning solution minimized 
the .solution score and the total elevation change, but it t(X)k the 
greatest amount of execution time to do .so, and generated solution 
paths that were longer than tho.se of the 3rd place solution. 

Some of the contestants and members of the Challenge mailing 
li.st mentioned the po.ssible use of Delaunay triangles 
<http://www.ics.uci.edu/~eppstein/gina/delaunay.html> in solving this 
Challenge. A collection of Delaunay triangles has the property that, 
for each edge in the collection, there is a circle containing the edge’s 
endpoints but not any other endpoints. The idea was that these 
triangles would Ix^ “be.si” in some .sense for finding optimal paths 
from [)airs of points. However, none of the submitted .solutions 
actually implemented this approac h. 

llie mp two .scoring solutions both tried a straightforward 
approach to defining triangles, one that I hadn’t anticipated when I 
defined the problem (although I probably should have). The.se two 
solutions selected an anchor point, .sorted the remaining points by 
the angle they formed from the anchor point, and formed triangles 
from the anchor point to the Nth and N+l *^^ points in angle from the 
anchor, ’fhis approach has the feature that there is a two-segment 
path between any pair of points, one from the first point to the 
anchor, and one from the anchor to the second point. Randy’s 
winning solution chose the anchor to be a point in the center of the 
set c^f points, while the second-place entiy of Jared Selengut chose 
the point arbitrarily. Randy’s solution looked for a path that was 
better than this initial two-segment path, an enhancement that did 
find a better .solution in one of my te.sts. Jared’s solution was much 
(juicker, but it found longer paths with greater elevation change 
than Randy’s winning solution. 

Krnst Munter’s solution actually found the shortest solutions, 
although the elevatic^n change was greater. Ernst’s approach was 
to build the triangles in progressively widening circles around a 
central point, 'fhe paths produced by his .solution had many more 
segments than the other two .solutions, resulting in a more direct 
path between the endjxiints, but the total elevation change was 
greater than that generated by either of the other two solutions. 

'fhe test scenarios consisted of a total of 18 test cases using 3 
data sets of 2500 points each. The table below lists, for each of the 
solutions submitted, the total execution rime for all test ca.scs, the 
total horizontal di.stance and elevation change for the paths 
generated, the total score for all test cases, and the code and data size 
of each solution. As usual, the number in parenthe.se.s after the 
entrant’s name is the total number of Challenge points earned in all 
Challenges prior to this one. 


Name 

Time 

Horizontal 

Elevation 

Score 

Code 

Data 


(m.sec) 

Distance 

Cliange 

lime 

Size 

Size 

Rjindy Boring (83) 3947.17 

71710.96 

3207.75 

118109.99 

9952 

1MB 

Jared Selengui 

142.63 

73702.69 

6282..39 

137171.56 

2044 

72 

Emsi Municr M30) 1729.30 

65972.19 

18157.13 

261376.67 

9312 

264 
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Top Contestaints 

Listed here are the Top 20 Contestants for the Programmer’s 
Challenge. The numbers below include points awarded over the 24 
most recent contests, including points earned by this month’s 
entrants. 


Raiik 

Name Points 

Rank 

Name 

Points 

1. 

Munter, Ernst 

205 

11. 

Nicollc, Ludovic 

27 

2. 

Saxton, Tom 

99 

12. 

Brown, Pat 

20 

3. 

Boring, Randy 

66 

13. 

Day, Mark 

20 

4. 

Rieken, Willeke 

47 

14. 

Hostettcr, Mat 

20 

5. 

Maurer, Sebastian 

40 

15. 

Hewett, Kevin 

10 

6. 

Hcithcock, JG 

37 

16. 

Jones, Dennis 

10 

7. 

Murphy, ACC 

34 

17. 

Selengut, Jared 

10 

8. 

Lewis, Peter 

31 

18. 

Smith, Brad 

10 

9. 

Mallett, Jeff 

30 

19. 

Varilly, Patrick 

10 

10. 

Cooper, Greg 

27 

20. 

Webb, Rus.s 

10 


There are three ways to earn points: (1) scoring in the top 5 of 
any Challenge, (2) being the first person to find a bug in a published 
winning solution or, (3) being the first person to suggest a Challenge 
that I use. The points you can win are: 


1st place 20 [)oints 

2nd place 10 points 

3rd place 7 points 

4th place 4 points 

5th place 2 points 

finding bug 2 points 

suggesting Challenge 2 points 


Here is Randy’s winning Terrain Traversal solution: 

FindAPatli.c 

Copyright © 1999 Randy Boring 

r 

* Simple solution: two-part path! 

make radial de.sign triangles to a central point 

* solve by traversing to center, then to destination 
V 

^include “FindAPath.h” 

^include <fp.h> 

^/include <MacMemory .h> //tor NewPtr, etc. 

//pragma mark = Top == 

//define TNPUT_TS_SORTED 0 
//def ine MYDEBUG 0 

//if MYDEBUG 

//define kGarbage (OxA3A3A3A3) 

//define kGarbage2 (0xA3A5A4A3) 

//define kGarbage3 (OxASASASAS) 

//define ASRT_TYPE 1 
//if ASRT_TYPE == 2 
//include <assert.h> 

//define ASSERT(cond) assert(cond) 

//else 

//define ASSERT (cond) if (cond) ; el.se DebugStr(“\p 
assert failed!”) 

//endif 

//else 

//define ASSERT (cond) 

//eiidif 


// skew the weight of the l (height) axis, since it is skewed 
// in the scoring of our Solutions. 

//define kHeightWeight (8.0) // .should be up around 100.0 since it’s squared 

//define kTwoPi (pi * 2.0) 

//define IdxOfPt(pt.ptarray) ((pt) (ptarray)) 

//define kNoTriangle ( l) 

//define kMaxPoinls (32 * 1024L) 

// globals 

static long gCenterldx; //index of center point 

//if INPUT_IS_SORTED 

// ‘fix’ the numbering of points (off by one) 

//define PtNumToTdx(n) ((n) 1) 

//define TdxToPtNum(p.i) ((i) + 1) 

//el se 

// ‘fix’ the numbering of points (create mapping of number to index!) 
static long gPtNumToIdxMap[kMaxPoints]; 

//define PtNumToIdx(n) (gPtNumToIdxMap [ (n) - l]) 

//define IdxToPtNum(p.i) ((p) [i] . thePolniNum) 

static void 

MakePtNumToIdxMap(const Point3D p[], long pCount) 

( 

long i: 

for (i = 0; i < pCount; i+i) 

gPtNumToIdxMap(p[i].thePointNum - 1] “ i; 

) 

static void 

DisposePtNuraToIdxMap(void) 

( 

DisposePtr((Ptr) gPtNumToIdxMap); 

I 

//endif 


Disl 

// Return a measure of the distance, given the deltas, but 
// wciglit the height (z) axis most, as this has the most 
// weight in our Solution's score, 
static double 

Dist(double dx, double dy, double dz) 

{ 

return (dx * dx + dy * dy + dz * dz * kHeightWeight) : 

) 


FindMiddleDotIdx 

// Return the index of the middle-mo.st point 
static long 

FindMiddleDotIdx(const Point3D p[]. long numPoints) 

( 

double totX =0.0. totY =0.0. totH =0.0; 
double aveX. aveY. aveH: 
double denom - 1.0 / numPoints: 
double bestDX, bestDY, bestDH. closestDist; 
long i. besti; 

// find average x, y, ht 

for (i =0; i < numPoints: i++) 

{ 

totX += p [ij.thePoint.x; 
totY p [i].thePoint.y; 
totH += p [i].ht; 

I 

aveX = totX * denom; 

.aveY ~ totY * denom: 

aveH = totH * denom; 

bestDX = aveX - p[O].thePoint.x: 

bestDY = aveY - p[0j.thePoint.y; 

bestDH = aveH - pfoj.ht; 

besti = 0; 

closestDist = Dist(bestDX, bestDY. bestDH); 

// find lowest distance to average 

for (i = 1: i < numPoints; i++) 

{ 

double dH. dX. dY. thisDist; 
dX = aveX - p[i].thePoint.x; 
dY = aveY - p[i].thePoint.y; 
dH = aveH - p[i]-ht; 
thisDist = DisL(dX. dY. dll); 
if (closestDist > thisDist) 
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{ 

closeslUist = thisDist; 
besti = i: 

} 

} 

return besti; 

) 


ItadiansBctwecnOld 

//Absolute radians of the vector from point c to point i 
static double 

RadiansBetwe€n01d(long c, long i, const Point3D pfl) 

I 

double dx = p[i].thePoint.x - p[c].thePoinl.x; 
double dy = pfil.thePoint.y - p[c].thePoint.y; 
double angle = atan2(dy, dx); 
return angle: 

I 


Radianslieiween 

// Absolute radians of llie vector from |)oint 0 to point I 
.static inline double 

Rad iansBetween(double xO. double yO. double xl. double yl) 

{ 

double dx ~ xl - xO; 
double dy = yl yO; 
double angle = ataii2(dy, dx) ; 
return angle: 

I 


MakeRadialConnection 

// Add the two points, c and pointi, to a pnHo-Triangle 
// (Tlic other leg will be added after sorting by angle) 
static void 

MakeRadiaiConnection(eonsi Point3D p(]. 
long pointi, long c. 

Triangle t[]. long ti) 

1 

double *angle = (double *) &(tIti].thePoints[1]); 

‘angle ” RadiansBetween(p[c].thePoint .X, p[c].thePoini.y, 
p[pojnti].thePoint.x, p[pointi].thePoint.y): 

// lIlil.ihcTrianglcNum = ti; // filled in later 

tItiJ .thePoints[0] = ldxToPlNum(p. pointi); 

I 


Cmp 

static t nt // positive if right less then left, zero if equal 
Cmp(eonsI void ‘left, const void ‘right) 

I 

Triangle *lt = (Triangle *) left; 

Triangle *rt = (Triangle *) right; 
double ‘Itval = (double *) 5({lL >LhcPoint.s [1]); 
double *rtval ^ (double *) &(rt->thePoinLs[1]); 
double diff = *ltval - *rtval; 
if (diff > 0.0) 
return I; 

else if (diff < 0.0) 
return 1: 
else 

return 0: 


SortTriangles 

#include <sidlib.b> 
r void qsort(void *base, size_t nmemb, size_t size, 
ini (‘compare) (const void *, const void *)) 7 
r this requires linking wiili MSL Std C Lib V 
static void 

SortTriangles(Triangle t[J. const long tCount) 

I 

qsorL(L, tCount. sizeof(Triangle), Cmp): 

) 


(ioneavcAngle 

// Return true if the angle difference, diff, represents 
// a ('.oncave angle, i.c., < 180 degrees (pi radians) 
static Boolean 
ConcaveAngle(double diff) 

( 

if (diff < pi) 
return true; 

r Bob guaranteed that this case would not ocair: 

The situation where a point lies exactly along an 


edge bctw'ccn two other points will not arise.’V 
ASSKRT(diff != 0.0): 

if (diff <- 0.0) 
return false; 
if (diff < pi) 
return true; 
return false: 

) 


Perimeter Point List 

#pragma mark = Perimeter Point List = 

//This structure Ls for keeping track of the dimini.shing 
// list of points that make up the ‘|K*rimeicr’ around the 
// triangles. 

// As the concavities’ arc filled up, points in this list 
// are no longer on the perimeter and so arc removed. 

//Tlic process stops when the perimeter is convex 
// 'Hie ‘un-const’ Point3DPtr is still treated as ’const’ by me, 

// but 1 couldn’t figure out how to make the compiler let 
// me make const pointers into the point array otherwi.se. 
typedef Point3D * Point3DPtr: 
typedef struct I 
Polnt3DPtr ‘plist: 

Polnr3DPtr ‘plast; 
long size: 

1 PointList; 

// - // - // - // - // - // - // 

static void 

MakeListOfEdgePoints(Triangle t[]. long tCount. void ‘vp, 
con.st long badindex, PointList ‘list) 

( 

long i: 

Point3DPtr p = (Polnl3nPtr) vp; 

Point3DPtr *pp; 

list->piist = pp = (Poinl3D **) NewPtr(tCount * 
sizeof(Point3D)): 

if (list->plist nil) 

DebugStr(*’\p couldn't allocate point list!”); 
list >size = tCoiint; 
for (i = 0; 1 < badindex; ill) 

•pp++ = &(p[PiNuiiiToTdx(t.(i] .thePoints[0])]): 
if (badindex != 1) 

I 

•pp++ “ &(p[PtNumToIdx(t[i].thePoints[0])]); 

‘ppil = &(pfgCenterIdx]); 

1iGt->size++: 

; // i == badindex has been pnK:csscd 

) 

for (; i < tCount; i++) 

*pp-H- = &(p[PtNumToIdx(t[1].thePoints [0] )1 ); 
list->plast ^ pp; 


static void 

DisposeLlst(PointList ‘list) 

I 

DisposePtr((Ptr) list >plisl); 

Hf MYDEBUG 

list->plist = (struct Point3D **) kGarbage; 
list->pla.st = (struct Point3D “) kGarbage2; 
list >size = kGarbage3; 

#endif 

1 

//define GetEdgePointCount (1) ((1) >slze) 

//define SetEdgePointCount(l.s) ((1) >si 2 e = (s)) 
//define RemoveEdgePoint (1 .p) (*(p) = nil) 

// - // - // - // - // - // - // 

// Find first non-nil ptr in array 
static Point3DPtr * 

GetFirstEdgePoint(PointList ‘list) 

{ 

Point3DPtr *p = list->plist: 
while (*p = nil) 
f+p; 

ASSERT(p < list->pla.st); 
return p: 

1 
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-// 


//-//-// - // - // - // - 

// Slarling ai p, find next non-nil ptr in array 
// Returns nil if no more, else 

// Returns pointer to array element containing the non-nil ptr 
static Point3DPtr * 

Get.NextEdgePoinL (PointList ‘list, Point3DPtr *p) 

{ 

PointSDPtr “stop = list->plast; 

Poirit3DPtr ‘found - nil; 
while (++P < stop) 
if (*p != nil) 

{ 

found = p; 
break; 

) 

ASSERT(p <! stop); 
return found: 

1 

//-//-//-// - // - // - // 

// Return true if when looking from pi to p3,p2 is on the left 

//This means that a triangle can be constructed of these 

// points, making the perimeter more convex (removing a concavity). 

.static Boolean 

Concave (const Point3D *pl, const PointlD *p?., const Point3D 
*p3) 

{ 

double r21 = RadiansBetweGn{p2->thePoint.x, p2'>thePoint.y, 
pi->thePoint.x. pi->thePoint.y); 
double r23 = RadiarisBetween(p2->thePoint.x, p2->thePoint.y. 

p3->thGPoint.X. p3->thePoint.y); 
double diff = r23 - r21; // angle (in radians) at point 2 
return ConcaveAngle(diff); 


static void 

AddTriangle(Triariglo L [] , long tidx, 

PointlDPlr pi, Point3DPtr p2. Point3DPtr p3) 

{ 

// tltidxl.theTriangleNum = tidx; // filled in later 
t [tidx] . thePoints [0] = pi->thePoinLNLim; 
t [tidx] . thePoint.s [ 1 ] = p2 ^ihePointNum; 
t ftidx] .thePoints [2] = p3->thePointNuni; 


//-//-// - // - // - // - // 

// Create more triangles by going around the perimeter once 
// and connecting edge points that can ‘see' each other. 

// Returns how many more were created 
static long 

Convexify(PointT.ist ‘list. Triangle t[]. long tCount) 
I 

PoinL3DPLr ‘firstpt, *ptl, *pt2. *pt3; 
long edgePtCount = GetEdgePointCount (1 i.st) ; 
long moreTriangles = 0; 
firstpt - ptl = GetFirstEdgePoint(list) ; 
pt2 = GetNextEdgePoint (1 iSt, ptl): 

ASSERT(pt2 != nil); 
do ( 

pt3 = GetNextEdgePoint(list, pt2); 

ASSERT(pt3 !=nil): 
if (Concave(*ptl, *pt2, *pt3)) 

{ 

AddTriangle(t, tCount, *ptl, *pL2. *pt3); 

tCount+T; 

moreTriangles++; 

RemoveEdgePolnl(list. pt2); 
ptl pL3; 

if (-edgePtCount > 2) 

pt2 = GetNextEdgePoint(list, ptl); 

1 

else { 

ptl = pt2; 
pt2 = pt3; 

J 

} while (-edgePtCount > 2) ; 

// last two wrap around, pulling pi into p3 and p2 positions 
if (*pt2 = nil) //last triangle was concave 
f 

pt2 ^ firstpt; 

pt3 = GetNextEdgePoint(list, firstpt); 
if (Concave(*ptl, *pt2, *pt3)) 


AddTriangle(t, tCount, *ptl. *pt2, *pt3); 

tCotint++; 

moreTriangles++; 

ReraoveEdgePoint(list. pt2); 

) 

) 

else f 

pt3 “ firstpt; 

if (Concave(*pt1, *pt2, *pt3)) 

{ 

AddTriangle(t, tCount, *ptl, *pt2, *pt3); 

tCount+H-; 

iiioreTriangies++; 

RemoveEdgePoint(list, pt2); 

} 

else { 

ptl = pt2; 
pt2 = pt3; 

pt3 = GetNextEdgePoint(list, pt2); 
if (Concave(*ptl, *pt2, *pt3)) 

{ 

AddTriangle(t, tCount, *ptl, *pt2, ‘pt3); 

tCount++; 

moreTriangles-H-; 

RemoveEdgePoint(list, pt2); 

) 

I 

) 

// reduce the count of points on the perimeter by the number 
// of triangles we created this pass 
SetEdgePointCount(list, 

GetEdgePointCount(list) - moreTriangles); 
return moreTriangles; 

) 

// - // - // - // - // - // - // 

// Interconnect more edge’ points into triangles 
// Returns new triangle count 
static long 

MakeMoreTriangles(Triangle t[], long tCount, 
const PoinLlD p[], PointList *listp) 

( 

#pragma unused (p) 

long moreTriangles = 0; 
do f 

moreTriangles = Convexify(listp, t, tCount); 
tCount += moreTriangles; 

1 while (moreTriangles > 0); 

Di.sposeList (listp) ; 
reLurn tCount; 

) 

//-// - // - // - // - // - // 

// Note: If the set of points can form a convex polygon, 

// (or the mid-most point is on the outside for any reason), 

// then this algorithm would produce an “overlapping triangle” 

// because one of its angles is greater than 180 degrees (i.e., 

// it is upside down) without the ConcaveAngle check. 

// Returns how many triangles were made. This should be 
// tCount, unless there was an inverted triangle, in which ca.se 
// it will be iCount -1 
static long 

MakePerimGterConnection.s(Triangle t[]. const long tCount. 

const Point3D p[]. const PointNum enum, PointList *listp) 

( 

long i, badlndex = -1; 

double angleLast = ‘(double ‘)&t [0].thePoints[1] ; 

double angieLastOriginal = angleLast; //save for wraparound test 

double angleNext; 

for (i = 0; i < tCount - 1; i++) 

( 

angleNext = ‘(double *)&t[i + Ij.thePoints[1] ; 
if (ConcaveAngle(angleNext - angleLast)) 

{ 

t[i].thePoints[2] = t[i I 1] .thePoints[0] ; 
t [ij .thePoints[1] = enum; 
angleLast = angleNext; 

} 

else { 

r we can have only ONE inverted triangle to skip 7 
ASSERT(badlndex = -1); 
badlndex = i; 

) 

) 
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// wraj) around to the beginning 

angleNext = angleLastOriginal; 

if (ConcaveAngle(angleNext - angleLast)) 

I 

t [tCount - ll.thePoints[2] “ t [0].thePoints[0]; 
iftCount - I].thePointsfll = enum; 

1 

else 

badindex = tCount 1; 

MakeListOfEdgePoints(t, tCount. (void *) p. badindex. listp): 
// actouni for poj>!»iblc bad triangle 
if (badindex !“ *1) 

{ // shift all triangles above badindex down one 

BlockMovoData((Ptr) &t [badlndex+l], (Ptr) &t [badindexj, 
(iCounl 1 - badindex) * sizeof(Triangle)); 
return LCounL 1; 

) 

return tCount: 


// - // - // - // - // - // - // 

// Make the triangles that connect each point with the center point 
// Return the number of triangles created (pCount - I or 2) 
static long 

MakeRadialTrianglesdong center, const PointlD p[]. long 
pCount, Triangle tLJ) 

I 

long i, tCount; 

PointT.ist list; 

for (i * 0; i < center; lit) 

MakcRadialConnection(p. i, center, t. i); 

// don’t connect center with itself! 

for (i = center + 1; i < pCount: i++) 

MakeRadialConnection(p. i. center, t, i 1); 
tCount = pCount - 1; 

SortTriangles(t, tCount); 

tCount = MakePerimeterConnections(t, tCount. p, 
IdxToPtNiim(p, center), &list); 
tCount = MakeMoreTrianglcs(t, tCount, p, &list); 
return tCount; 

1 

//if MYDEBUG 
static void 

DbgWriteTrtangles(long c, const PointlD p[]. Triangle t[J, 
long tCount) 

1 

FILE *dbgf = f open ("triangles, out **, "w"); 
long i: 

const Point2D *pt - &(p[cj.thePoint); 

fprintf(dbgf, “center ^ ^ (%f. %f)\n\n", c, pt->x. pt >y): 
fprintf(dbgf, 

"\n tri \tp0 \tpl \tp2 \t(x, y) of p0\n"); 

for (i = 0; i < tCount: i++) 

I 

const Point2D ‘ptO; 

PointNum pnumO = tlij.thePoints[0]; 
ptO 6t(plPtNuinToIdx(pnum0) J .thePoint); 
fprintf(dbgf. "%d \t%d \t%d \t%d \t(%f. %f)\n". 

i, pnumO, tfi].thePoints[1], tlij.thePointsl2j. 
pt0->x. pt0->y); 

I 

fclose(dbgf); 

) 

#endif 


Ncighlx)r Mapping 

//pragma mark = Neighbor Mapping = 

//Tliis mapping helps iterate over the neighbors of a point 

//define kEndOfNeigiiborList ( 1) 

^define kMaxSniallNcighbors (3)// kiicr 5-7 

^define kExiraNeigliborbyics (2)// later 32 (bytes = 16 more neighbors) 

//define kLastSmallNeighbor (kMaxSmallNeighbors - 1) 

typodcf struct NMap I 

short** moreNeighborsH; // excess neighbors (more than kMaxSmallNeighbors) 

shon nCount; // count of neighbors 

short smallNeighbors[kMaxSmallNGighbors]; 

1 NeighborMap: 

static NeighborMap gNeighborMap[kMaxPointsJ: 


static long gpCount; 
static void 

ClearNeighborMap(const long pCount) 

I 

long i: 

gpCount = pCount; // for dealkxating later 
for (i = 0; i < pCount; 1++) 

{ 

gNeighborMapLij.moreNeighborsH = nil; 
gNeighborMap[ij.nCount = 0: 

//if KYBEBUG 

gNeighborMap[i].smallNeighborsfOl “ kGarbage; 
//end if 
I 


//-//-//- if -//-//-// 

// add pt2 to ptl’s neighborlist 
static void 

AddlNoighbor(short ptl. short pt2) 

( 

long i. count = gNeighborMap[ptI].nCount; 

short *np = gNeighborMap[ptl].smalINcIghbors; 

long stop = (count > kMaxSmallNeighbors) 

? kMaxSmallNeighbors : count: 

short **h; 

for (i =0; i < stop; iH) 
if (npLij = pt2) 

return; // already a neighbor 

if (count < kMaxSmallNeighbors) 

I // there is room in the small neighbor list 
gNeighborMap[ptl].smallNeighbors[count] = pt2: 
gNeighborMap[ptl].nCount = count + 1: 
return; 

1 

else if (count ~ kMaxSmallNeighbors) 

I // time to allocate Handle for more neighbors 
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ASSERT(gNeighborMaplptlj.moreNeighborsH = nil); 
h (short **) NewHandle(kExtraNeighborBytes): 
if (h “ nil) 

DGbugStr(“\p couldn’t allocate extra neighbors handle”): 
gNeighborMapfpti].moreNeighborsH = h; 

**h - pt?.; 

gNcighborMap[ptl].nCount = count + 1; 
return; 

1 


ASSERT(G€tHandleSize((Handle) gNeighborMap[ptl].moreNeighborsH) 
>“ 2 •(count * kMaxSmallNeighbors)); 
np = *gNeighborMap[ptl].moreNeighborsH; 
stop = count kMaxSmallNejghbors; 
for (1 0; i < stop; i++) 

if (iip[i] = pt2) 

return; // already a iiciglibor 

// didn'l find pl2 in neighbor list, we ll have to add it 
h “ gNeighborMapfptll.moreNeighborsH; 

// check to see if we need to resize handle 

ASSF.RT(stop * 2 <- GotHandTeSizc( (Handle) h)); 

if (stop * 2 ” GeiHandleSize((Handle) h)) 

I 

SetHandleSize((Handle) h, stop * 4); 
if (GetHandleSize((Handle) h) stop • 4) 

DebugStr(“\p couldn’t resize handle for more neighbors!”); 

I 

// add to handle list 
•((♦b) + stop) - pi2; 
gNejghborMap[pil].nCount = count + 1; 


// - // - // - // - // - // - // 

// add pt2 to ptl’s neighborlist and ptl to pt2’s 
static void 

AddNeighbors(short ptl, short pt2) 

I 

AddlNeighbor(ptl. pt2); 

AddlNeighbor(pt2, ptl); 


static void 

LockNeighboi Handle.s (void) 

( 

long i; 

for (i = 0; i < gpCount; i-H-) 

if (gNeighborMap[i].nCount > kMaxSmallNeighbors) 

I // must have handle when we have more neighbors 
ASSERT(gNeighborMapfi).moreNeighborsH != nil); 
HLock((Handle) gNeighborMap[1].moreNeighborsH): 
1 

else // no handle when neighbors fit in small array 

ASSERT(gNeighborMap[i].moreNeighborsH = nil); 

1 


// - // - // - // - // - // - // 

// Ignores center point because our algorithm will first use 
// the center to find an initial solution. Tlicrefore no 
// aronnd-thc-edge .solution will need to go through the center, 
sialic void 

MakeNeighborMap(const Triangle t[J. const long tCount. 

const long pCount) 

I 

long i ■ -1; 

ClearNeighborMap(pCoiint); 
while (t[++i1.thcPoinis [1] = gCenlerldx) 
AddNeig}»bots(PLNumToidx(L [i] . thePoints [0]). 

PtNuniToIdx{t [ij . thePoints [2J)); 
for (; i < tCount: i++) 

I 

AddNeighbors(PtNumToIdx(tfi].thePointsfOl). 

PtNumToIdx(t[i].thePointsfl])); 

AddNeighbors(PtNumToTdx(t[i].thePoints[l]), 

PlNumToidx(t[i].thePoints[2])); 
AddNeighbors(PtNumToIdx(tliJ.thePointslOj). 

PtNumToIdx(tlij.thePoints[2])); 

1 

LockNeighborHandlesO ; 


sialic void 
DisposeNeighborMap() 


( 

long i; 

for (i = 0; i < gpCount; 1 ++) 

if (gNeighborMap[l].nCounl > kMaxSmallNeighbors) 

DisposcHandleC(Handle) gNeighborMap[iJ.moreNeighborsH); 

) 


static inline long 
FirstNeighborClong pti) 

I 

ASSERT(gNeighborMapfpti).nCount > 0); 
return gNeighborMap[pti].small Noighbors[0]; 


// - // - // - // - // - // - // 

// returns next neighbor’s point index 

// searclies for previous neighbor in list and returns the next one 
// or khndOfNcighborList (-1) if there is no next one 
static long 

NextNeighbor(long ptl, long neighbor) 

1 

long i. count = gNeighborMap[pti].nCount; 
short *np = gNeighborMap[ptij.smailNeighbors; 
long stop = (count > kMaxSmallNeighbors) ? 

kMaxSmallNeighbors : count; 

short ••h; 

for (i = 0; i < .stop; 1++) 
if (np[i] = neighbor) 
break; //found neighbor 
if (i < stop) 

( // found neighbor in small list 

if (i 1 < stop) //tliere are more in the small list 

return gNeighborMap[pti].smailNeighbors[i i ll; 

// else, there are no more in the small list 

if (i + 1 < kMaxSmallNeighbors)//was there r(X)m for more? 

return kEndOfNeighborLisl; // then, that was the last one! 

// else, found at end of a full small list 

if (i + 1 < count) //are thea-morc neighbors? 

I // next neighbor is the first in ilie Handle 
h - gNeighborMap[pti].moreNeighborsH; 

ASSERT(h != nil); 
return **h; 

) 

// else, no more at all 

return kEndOfNeighborList; 

1 

// not found in small list 

if (count = kMaxSmallNeighbor.s) //there are no more 
return kEndOfNei ghborT.i st; 

// have to search the handle’s entries 
np *gNeighborMaplpLi].moreNeighborsH; 
stop = count - kMaxSmallNeighbors: 
for (i = 0: i < stop; 1++) 
if (npLij — neighbor) 
break: // found neighbor 

ASSERT(i < stop); // otherwise neighlx)r wa.sn’t Ibund! (misuse of this routine) 

// check to .see if we are at end of neiglibor li.st 
if (I + 1 < slop) //there are more in handle’s list 
return np[i + l] : //next neighbor 
else // found neiglibor was the last one- 

return kEndOfNeighborList; 


InitTerrainMap 

// Interconnect the points into triangles of my cluKising 
// My strategy is to make thin triangles from every point to 
// a central point. This way there is always a two-step (max) 

// path between any two points, and that path won't have much 
// elevation change. 

//'fhen I improve that set by filling in the edges so that 
// the perimeter is concave. Tliis way, alternate paths may 
// be found between .some pairs that are shorter than going 
// through the center, 
long /‘nurnTriangles*/ 

InitTerrainMap( 

const PointlD thePoints [J, 
long numPoints, 

Triangle theTriangles[]) 

I 

long i, nurnTriangles; 
long cGiiter: 

#if !1NPUT_1S_S0RTED 

MakePtNumToIdxMap(thePoints, numPoints): 

//end if 
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center = FindMiddleDotIdx(thePoints. numPoints); 
gCenterldx = center; 

numTriangles = MakeRadialTriangles(center, tbePoinls, 
numPoints. thoTrianglcs); 

#if MYOEBUG 

DbgWriteTriangles(center. thePoints, 
theTriangies. numTriangles); 

#endif 

// now number the triangles 
for (i = 0; i < numTriangles; i++) 
theTriangles[i].theTriangleNum = i; 
MakcNclghborMap(lhoTrianglGS, numTriangles, immPoints); 
return numTriangles; 


TermTerrainMap 

// release anything alloealed in initialization 
void 

TermTerrainMap(void) 

{ 

#if !iNPUT_iS_SORTED 
DisposePtNumToIdxMapO; 

#endif 

DisposeNeighborMapO ; 

1 


ContainsPoint 

// Return true if the point (x,y) is one of the points 
static Boolean 

ContainsPoint(const PointlD plJ, const PointNum pnl3]. 
double X, double y) 

1 

long j; 

for (j = 0; j < 3; j++) 

( 

long pLi = PLNuinToldx(pn[j]) ; 
if {p(pti].thePoint .X = x && 
p(pti].thePoint.y = y) 
return true; 

} 

return false; 

I 


FindTria ngleCon t a i n i ng 

// Return the index of the triangle containing both 
// ix)im 1 (xl.yl) and |X)int 2 (x2,y2) 
static long 

FindTriangleContaining(const Point3D pfl. 
const Triangle tfl, long tCount, 
double xl. double yl. //point 1 
double x2, double y2) //point 2 

I 

long i; 

if (xl = x2 && yl = y2) 

return kNoTriangle: // points are the same 
for (i ^ 0: i < tCount; i -H-) 

if (ContainsPoint(p. tfil .thePoints, xl, yl) ftfi 
ContainsPoint(p, t[i].thePoints, x2. y2)) 
return i; 

DcbugStr(“\p didn’t find the triangle!”); 
return 2; // failure! 


FindPtldx 

// Find the index of the point with coordinates (ptx, pty) 

//This is a linear search through the point list, don’t do 
// it very often! 
statle long 

FindPtldx(corist Poiiit3D p(], long pCount, 
double ptx. double pty) 

I 

long i; 

for (1 = 0; i < pCount; i++) 
if (p[il .thePoint.x = ptx ftft 
p[i].thePoint.y pty) 
return i; 

DebugStr(**\p point not found anywhere!"): 
return -1; 


('ostBetw'een 

// returns the cost between two points 

// computed as per ('hallenge Statement: the distance bemeen 

// the two (2D) points plus ten times the height difference 


Quadrivio General Edit 


Debug & Analyze 
Complex File Formats. 




( 3 ) 

(2) 


□ = UNTITLED 


(I) 


A 


1) Define your format with familiar, C-like statements. 

2) View, analyze, and edit data file in up to 5 columns. 

3) View and edit file parameters. Also edit handle blocl<s 

and other data structures in memory. 


Free! 

Lite & deinu veniiuiis 
available on web sire. 


✓ Quick insight into data structure contents. 

^ Easier than studying MPW’s dumpfile output, 
i/ Faster debugging with clear display of data. 

✓ Saves coding time with direct data editing. 


Visit our web site for immediate download. 

On-line ($195) and boxed ($249) versions available. 

Also available from Developer Depot & SciTech International. 


http://www.quadrivio.com 


Quadrivio Corporation info(®quadrivio.com 
1563 Solano Avenue #360 Berkeley, CA 94707 (510)524-3246 


// (as ail absolute value), 
static double 

CostBetweendong ptAi, long ptBi. const Point3D p[l) 
I 

double dx, dy, dht; 
dht ~ p[plAi].hi; 
clx = p[ptAi] .thePoint.x; 
dy = pLptAi].thePoint.y; 
dht -= piptBiJ.ht: 
dx -- piptBi].thePoint.x; 
dy *= pfptBil.thePoint.y; 
dht •= 10.0; 
dx dx; 
dy *“ dy; 
if (dht < 0.0) 
dht = -dht; 

return sqrt(dx + dy) + dht: 


CostOfSegmentPath 

// returns co.si of whole path (given as list of Segments) 

// computed by adding cost between the startingPoint and the 
// endingPoint of each Segment, 
static double 

CostOfSegraentPath(Segment sLl. long sCount, 
const PointSD p[], const long pCount) 
i 

double total = 0.0; 
long i; 

long ptAi = FlndPtTdx(p, pCount, 

s(0] .StartingPoint .x, s [0] .slarliiigPolnL .y); 
for (i = 0: i < sCount; i-H-) 

I 

long ptBi “ FindPtldx(p, pCount, 

sfil.endingPoint.X, sfil.endingPoint.y); 
total += Co.‘;tBetween(ptAi, ptBi, p); 
ptAi = ptBi; 

1 

return total: 

I 
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Search Queue & Paths 

^pragma mark = Search Queue & Paths == 

//This structure is the heart of my depth-first-search 
// It is both a search queue element and a path element 
typedef struct QE ( 

struct QE * nextSearchSQ; //32K max (+2 sentries) 

// short ptldx; //32Kmax 

unsigned short nextPathQEi; //32K max (+2 sentries) 
short refCount: // path points are shared 

double costSoFar; // total cost of folowing this path 

} SearchQueueElem, *SearchQueue, *Path, **SearchQueuePtr; 
#define IdxOfPath(p) ((p) - gQ) 

//define IdxOfSQ(q) ((q) - gQ) 

//define CostOfPath(p) ((p)->costSoFar) 

//define Idx2Path(ptidx) (&(gQ[ptidx])) 

//define Idx2SQ(qidx) (&(gQ[qidx])) 

//define NextSQOf(q) ((q) •>nextSearchSQ) 

//define NextSQIdxOf (q) (IdxOfSQ(NextSQOf(q))) 

//define SetNextSQOf(q.nq) (NextSQOf(q) = (nq)) 

//define NextPathIdxOf (p) ((p)->nextPathQEi) 

//define NextPathOf(p) (Idx2Path(NextPathIdx0f(p))) 

//define SetNextPathOf(p,np) (NextPathIdxOf(p) = IdxOfPath(np)) 
//define RefCountOf (p) ((p)->refCount) 

//define kMaxQE (kMaxPoints) 

//define kLastValidQEi (kMaxQE - 1) 

//define kLastPath (kMaxQE + 1) 

//define kLastQE (kMaxQE + 2) 

static SearchQueueElem gQ[kMaxQE + 3]; 

// Sentry values (not nil, so I can tell whether an clement is 
// in a path or queue, even at the end of it) 
static const SearchQueue gkLastSQ = &gQ [kLastQE]; 
static const Path gkLastPath = &gQ[kLastPath] ; 

// - // - // - // - // - // - // 

static void 

InitSearchQueue(SearchQueuePtr qp. const long pCount) 

{ 

long i; 

for (i = 0: i < pCount; i++) 

( 

gQ[i].nextSearchSQ = nil; 
gQ[il.refCount = 0; 

//if MYDEBUG 

gQ[i].nextPathQEi = kGarbage; 
gQ[i].costSoFar = (double) kGarbage; 

//endif 

1 

*qp = gkLastSQ; 

} 

// - // - // - // - // - // - // 

static void 

DelnitSearchQueue(SearchQueuePtr qp) 

{ 

//pragma unused (qp) 

) 

IsEmptySearchQueue 
static inline Boolean 
IsEmptySearchQueue(SearchQueuePtr qp) 

( 

ASSERT(qp != nil); 

ASSERT(*qp >= &gQ[0]); 

ASSERT(*qp <= gkLastSQ); 

ASSERT(*qp !“ gkLastPath); 
return (*qp = gkLastSQ); 

) 

// - // - // - // - // - // - // 

static inline Boolean 
AlreadyInSearchQueue(Path p) 

{ 

ASSERT(p != nil); 

ASSERT(p != gkLastSQ); 

ASSERT(p != gkLastPath); 
return (nil != NextSQOf(p)); 

} 

// - // - // - // - // - // - // 

//Add to search queue in sorted order Qeast co.st at front) 
static void 

AddToSearchQueue(SearchQueuePtr qp. Path p) 

I 

double pCost; 

SearchQueue q, lastq; 


ASSERKqp != nil); 

ASSERT(‘qp != gkLastPath); 

ASSERT(p != nil); 

ASSERT(p != gkLastSQ); 

ASSERT(p != gkLastPath); 
if (*qp = gkLastSQ) 

( 

*qp = p: 

SetNextSQOf(p, gkLastSQ); 
return; 

} 

lastq = nil; 
q = *qp; 

pCost = CostOfPath(p); 

while (q != gkLastSQ && CostOfPath(q) < pCost) 
I 

lastq = q; 
q = NextSQOf(q); 

) 

if (lastq == nil) 

*<1P = p; // add p to head of list 
else // insert p after lastq 

SetNextSQOf(lastq, p); 

SetNextSQOf(p, q); 


// - // - // - // - // - // - // 

// Remove from the queue the least cost path 
// Hint: it’s at the front! 

// Docs NOT remove it from path NOR releases it 
// DOES set nextSQ to nil 
static inline Path 
RemoveBestElem(SearchQueuePtr qp) 

{ 

Path p = *qp; 

ASSERT(p 1= nil); 

ASSERT(p 1= gkLastSQ): 

ASSERT(p != gkLastPath); 

*qp = NextSQOf(p); 

SetNextSQOf(p, nil); 
return p; 

} 

// - // - // - // - // - // - // 

// Remove from the queue the given path 
// Does NOT remove it from path NOR releases it 
// DOES set nextSQ to nil 
static void 

ReraoveFromSearchQueue(SearchQueuePtr qp, Path p) 

I 

Path seek, seekLast; 

ASSERT(qp 1= nil); 

ASSERT(*qp != gkLastSQ); 

ASSERT(*qp 1= gkLastPath); 

ASSERT(p 1= nil); 

ASSERT(p 1= gkLastSQ); 

ASSERT(p != gkLastPath); 
seekLast = nil; 
seek = *qp; 
while (seek 1= p) 

( 

seekLast = seek; 
seek = NextSQOf(seek); 

ASSERT(seek 1= nil); 

ASSERT(seek 1= gkLastSQ); 

) 

if (seekLast == nil)//p was first in list 
*qp = NextSQOf(p); 

else // make the node before p point to the one after p 
SetNextSQOf(seekLast, NextSQOf(p)); 
SetNextSQOf(p, nil); 


// - // - // - // - // - // - // 

static Path 

MakeFirstPathdong pointidx) 

{ 

Path p “ Idx2Path(pointIdx); 

ASSERT(p >= gQ); 

ASSERT(p <= &(gQ[kLastValidQEl])); 

SetNextPathOf(p, gkLastPath); 

SetNextSQOf(p. nil); 

RefCountOf (p) = 64; //anomoly to prevent loops at beginning 
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CostOfPath(p) = 0.0; 
return p; 

) 

// - // - // - // - // - // - // 

static inline void 

AddPath(Path oldp, Path newp, double newTotalCost) 

{ 

ASSERT(oldp 1= nil); 

ASSERT(newp != nil); 

ASSERT(newTotalCost > CostOfPath(oldp)); 

ASSERT(RefCountOf(newp) = 0); 

SetNextPathOf(newp, oldp); 

CostOfPath(newp) = newTotalCost; 

RefCountOf (oldp) IH ; // oldp becomes interior node 

} 

n - u - n - u - n -//- n 

static void 
ReleasePath(Path p) 

{ 

ASSERT(p != nil); 

ASSERT(p != gkLastSQ); 
if (p = gkLastPath) 
return; 

if (RefCountOf(p) == 0) 

ReleasePath(NextPathOf(p)); 
else 

RefCountOf(p)-; 


// - // - // - // - // - // - // 

// Returns the number of segments, i.e., jumps between path nodes 
static long 
PathLength(Path p) 

( 

long len = -1; 

ASSERT(p != nil); 

ASSERT(p != gkLastPath); 

ASSERT(p != gkLastSQ); 
do { 

p =" NextPathOf (p) ; 

++len; 

} while (p != gkLastPath); 
return len; 


// - // - // - // - // - // - // 

// Record the segments that make of this (newer) better path 
//The path is from end to start,so work backwards 
// NOTE: this will fail if the path is size zero 
static void 

RecordPath(Segment s[J, long *sCount. Path path, 

const PointSD p[], const Triangle t[], const long tCount) 

{ 

double xE, yE, xS, yS; 

long len = *sCount *= PathLength(path); 

long triNum; 

xE = p [IdxOfPath(path)].thePoint.x; 
yE = p [IdxOfPath(path)].thePoint.y; 

ASSERTden > 0); 
do ( 

path = NextPathOf(path); 
len—; 

xS = p [IdxOfPath(path)].thePoint.X; 
yS “ p[IdxOfPath(path)].thePoint.y; 
triNum = EindTriangleContaining(p, t, 
tCount, xS, yS, xE, yE); 

ASSERT(triNum != kNoTriangle); 
s[len].theTriangleNum = triNum; 
s[len].startingPoint .X = xS; 
s[len].startingPoint.y = yS; 
s [len].endingPoint .X = xE; 
s [len].endingPoint.y = yE; 
x£ = xS; 
yE = yS: 

) while (len > 0); 

) 

#if MYDEBUG 
static long 

FindPtInTriangle(const PointSD p[], const PointNum pn[3]. 
double X, double y) 


{ 

long j; 

for (j = 0; j < 3; j++) 

( 

long pti = PtNumToldx(pn[j]); 
if (p[pti].thePoint .X = x && 
p[pti].thePoint.y == y) 
return pn[jl; 

I 

DebugStr(“\p couldn't find point in triangle!*'); 
return 1; 

1 

static void 

PrintPath(Segment s[], long sCount, const Point3D p[]. const 
Triangle t[l) 

I 

long i; 

for (i = 0; i < sCount; i++) 

{ 

long triNum. ptNumFrom, ptNumTo; 
triNum = s [i].theTriangleNum; 

ptNumFrom = FindPtInTriangle(p, t[triNum].thePoints, 
s [i].StartingPoint .X, s [i].startingPoint.y); 
ptNumTo = FindPtTnTriangle(p, t [triNum].thePoints, 
s [1].endingPoint.x. s [i].endingPoint.y); 
printf(“seg %d \l;%d \t%d \t%d”. 

i, triNum, ptNumFrom, ptNumTo); 
printf(“ cost=%f\n”. 

CostBetween(PtNumToIdx(ptNumFrom), PtNumToIdx(ptNumTo), p)); 

} 

} 

//endif 


EvaluateFinishedPath 

// Deal with a path to the end point 
// If it is a better path, 

// record it, release the old best path, and return the new value 
// otherwise 

// release the path (it wasn’t better), and return the old value 
// Return the current best path in *bestPath 
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static double 

EvaluateFinishedPath(Segment s[], long *sCount, 

const PointlD p[], const Triangle t[], const long tCount, 
Path path, Path *bestPath, double bestCost) 

{ 

double newCost; 

newCost = CostOfPath(path); 

if (newCost K bestCost) 

{ // found a better path to end!! 

RecordPath(s, sCount, path, p, t, tCount); 

#if MYDEBUG 

printf(“better path:\n’'); 

PrintPath(s, *sCount, p, t); 

//end if 

bestCost = newCost; 

ASSERT(bestPath != nil); 
if (*bestPath != nil) 

ReleasePath(*bestPath); 

*bestPath = path; 

} 

else 

ReleasePath(path); 
return bestCost: 


ExpandSearch 

// Expand the search from the given path endpoint ‘path’ 

// Expand by following each node that is neighbor to ‘path’ 

// Expand just one level, then return, 
static void 

ExpandSearch(SearchQueuePtr qp, const PointSD p[]. 

Path path, long pathidx, double bestCost) 

{ 

long follow; 

// expand search from partial path ending at ‘path’ 
for (follow = FirstNeighbor(pathidx); 
follow != kRndOfNeighborList; 
follow = NextNeighbor(pathidx, follow)) 

{ 

double newCost: 

Path followPath = Idx2Path(follow); 

ASSERT(follow != pathidx); 

// don’t go back on yourself (problem with neighbor logic) 
if (RefCountOf(followPath) > 0) 

{ // it’s an interior node, 

ASSERT( IAlreadyInSearchQueue(followPath) ); 

// should not be in search path 
continue;//skip it 
} 

newCost = CostOfPath(path) + CostBetween(pathidx, follow, p); 
if (newCost < bestCost) 

{ // survived cutoff 

if (AlreadyInSearchQueue(followPath)) 

// follow exists in ;molher path already 
if (newCost >= CostOfPath(followPath)) 

// new path not an improvement 
continue; 

else // remove to add in proper (.sorted) place 
RemoveFromSearchQueue(qp, followPath); 

AddPath(path, followPath, newCost); 

AddToSearchQueue(qp, followPath); 

} 

1 


SeardiAlternatePath 

// Search for a better path from start to end than the 
// thn)ugh-the-center route already in theSegments 
// If found, fill in theSegments and return its length 
// else, just return the old length (sCount) 
static long 

SearchAlternatePath(Segment s[l, long sCount. 
const PointlD p[], const long pCount, 
const Triangle t[], const long tCount, 
long ptIdxStart. long ptIdxEnd) 

{ 

double bestCost = CostOfSegmentPath(s, sCount, p, pCount); 
SearchQueue q; 

Path pathStartPtr, bestPath = nil; 

InitSearchQueue(&q, pCount); 
pathStartPtr = MakeFirstPath(ptldxStart); 

AddToSearchQueue(&q. pathStartPtr); 
do! 

Path path = RemoveBestElem(&q); 


long pathidx = IdxOfPath(path) ; 
if (pathidx = ptIdxEnd) //found a path to end! 
bestCost = EvaluateFinishedPath(s, &sCount, 
p, t, tCount, path, &bestPath. bestCost); 

else 

ExpandSGarch(&q, p, path, pathidx, bestCost); 

} while (!IsEmptySearchQueue(&q)); 
DelnitSearchQueue(&q); 
return sCount: 


FindAPath 

// Find a minimal cost path between the two points 
//First: 

// Comiect the start to the middle 
// Connect the middle to the end 
//Tlien: 

// Do a breadth-firsi search from start 

// Use the simple through-thc-center path as an optimizing cutoff 
long /^numSegmentsV 
FindAPath( 

const PointSD thePoints[], 
long numPoints, 

const Triangle theTriangles[] , 
long numTriangles, 
const Point2D pathStart, 
const Point2D pathEnd, 

Segment theSegments[] 

) { 

//pragma unused (numPoints) 
double xl, yl, xc, yc; 
long numSegments = 0; 
long triNumStart, triNumEnd; 

PointNum ptIdxStart, ptIdxEnd; 
xl = pathStart.x; 
yl = pathStart.y: 

xc = thePoints [gCenterldxJ.thePoint.x; 
yc = thePoints [gCenterldx].thePoint.y; 
triNumStart = FindTriangleContaining(thePoints. theTriangles, 
numTriangles, xl, yl, xc, yc); 
if (triNumStart != kNoTriangle) 

// triNum == kNoTriangle means pathStart IS center 
I 

theSegments[0].theTriangleNum = triNumStart; 
theSegments[0].startingPoint = pathStart: 
theSegments[O].endingPoint.x = xc; 
theSegments[0].endingPoint.y = yc; 
numSegments = 1; 

) 

ptIdxStart = FindPtldx(thePoints. numPoints, xl, yl); 
xl = pathEnd.x; 
yl = pathEnd.y: 

triNumEnd = FindTriangleContaining(thePoints, theTriangles, 
numTriangles, xl, yl. xc, yc); 
if (triNumEnd != kNoTriangle) 

// triNum == kNoTriangle means pathEnd IS center 

{ 

theSegments[numSegments].theTriangleNum = triNumEnd; 
theSegments[numSegments].StartingPoint .X = xc; 
theSegments [numSegments].StartingPoint.y = yc ; 
theSegments [numSegments].endingPoint = pathEnd; 
numSegments++; 

) 

//if MYDEBUG 

printf(“starting point: %f, %f\n”, pathStart.x, 
pathStart.y); 

printf (“ending point: %f, %f\n''. pathEnd.x, pathEnd.y); 

printf("initial path through center:\n”); 

PrintPath(theSegments, numSegments, thePoints, theTriangles); 

//end if 

if (numSegments > 1) // can’t improve a path of length one 

{ 

ptIdxEnd = FindPtIdx(thePoints, numPoints. xl. yl); 
numSegments = SearchAlternatePath(theSegments, numSegments, 
thePoints, numPoints, 
theTriangles. numTriangles, 
ptIdxStart, ptIdxEnd); 

1 

// else SearchAlternatePath is unnecessary (and fails!) 
return numSegments; 


m 
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FROM THE 
FACTORY FLOOR 


By Chuck Shotton and Dave Mark, ©1999 by Metrowerks, Inc., all rights reserved. 


A Conversation with Chuck Shotton 


'Ihis month's Factory Floor intermew is imth Chuck Shotton, 
blown by many as the Jather of Macintosh weh sen.iers. Chuck was 
the author of MacHTTP, the first Macintosh web server, which later 
became Webstar. Chuck took time out from, his latest 
groundbreaking progamming project to give us his side of the story. 


At various times, Chuck Shotton has toiled in tlie salt mines of 
defense contracting, under the yoke of academia, and in the trenches 
of private entei 7 )rise. His latest exercise in humility is as CEO of BIAP 
Systems, Inc. where he, along witli a cast of tliousands, altemates 
between groveling l^efore mighty VCs and flogging lowiy C 
compilers to do his bidding in a quest to create tlic Next Killer App 
(till) for die Internet. Comihg soon to a CRT near you! 

Dave: How did you get started with Mac Programming? 

Chuck: In one of my previous lives, 1 worked for a defense 
contractor in the Washington, DC area. One of the few firight 
spots in that otherwise Dilbert-esque landscape came along in 
late 1984 when we got our first Macs to play widi. Turns out 
that most of the guys in my department were old Apple 11 fans 
and a little anii-twisting resulted in some screaming 8 mHz, 
dual floppy 128k Macs. We were supposed to port a large 
chunk of ccxle from a Mix 11/780 to these Macs (which actually 
had more RAM than the Vax!) for a process management system 
used by the Navy. At that time, “Inside Mac” wasn’t really 
available and die total extent of the Mac programming 
documentation available to me consisted of back issues of 
MacTutor magazine and die Consulair C Compiler’s instaiction 
manual. So basically, 1 learned Mac prc’>gramming at uixpayer 
expense on a contract for the Navy by sitting around all day 
reading old magazines and disassembler output. 

My first real dose of uninhibited (read that “unclassified”) Mac 
programming didn’t come until 1986 when I started working 
on a contract in my spare time for Siniutronics, which 
developed most of the popular on-line games for the GEnie 
on-line service. I built the grapliical front end for Mac players 
of the “Orb Wars” game. I think that was the one and only 
time 1 ever got to work on game software for money and it’s 
been down hill ever since. 


Dave: What can you tell me about the early days of 
MacHTTP? 

Chuck: MacH'TTP was one of those life altering events that you 
don’t really know whether it was good or bad until a long 
time afterwards (turns out it was good — mostly). In late 
1992, mmors of this World Wide Web thing were floating 
around in the scientific community. Most people involved in 
academic information systems at the time (I was working at 
the U. of Texas in Houston then) were drooling over Gopher, 
Archie, and other text-based interfaces to existing Internet 
services. I decided to give the Web a try and began 
corresponding with the guys at CERN in Switzerland. Because 
almost everything was Unix-based at the time, I wanted to 
work on a Mac Web browser. Tim Berners-Lee wrote back 
that CERN had a great Mac browser in the works (anyone 
remember the CERN web browser?) and maybe I should look 
into writing a server for the Mac instead. 

So MacHTTP sprang into being in early ‘93 after an all night 
coding session. In its original incarnation, it handled exactly 
one connection at a time, had this Byzantine event loop that 
split its time between babysitting the MacTCP driver and 
looking for the user to type command-Q, and served anytliing 
on your hard disk. I still had to test it with a Unix browser until 
NCSA released the first Mac version of Mosaic, but the Mac OS 
was now the proud host of the second Web server on tlic 
planet after the Unix one created by the guys at CERN. 

Another 6 months of tweaking, fiddling, tuning, and very little 
interaction with sunlight resulted in the first shareware 
version of MacHTTP. By the middle of ‘94, MacHTTP had 
become the proverbial self-eating watermelon. Developing, 
testing, supporting, and selling a software product by 
yourself can get to be a herculean task. Even with my wife 
and 1 working at it (she was a C coding geek as well, though 
a reformed Ada zealot now), it was too much to do as a part 
time effort. We ended up flipping the baby, the bathwater, 
and my day job over the fence to StarNine Technologies in 
April of ‘95 and WebSTAR was born. 
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Dave: What lessons did you learn in bringing MacHTTP 
to market? 

Chuck: lake cash!. If you can grow a product into something 
lhai gets on peoples’ radar scopes, someone will offer to 
make your life easier by taking it off your hands, 'lake cash! 
Seriously though, I think the biggest lessons learned had to 
do with understanding how big companies (like Apple and 
Quarterdeck) do busine.ss and what technology-driven 
individuals have to do to survive in that commercial 
environment. Being able to build a community of users and 
develo|)ers around a product and stay with it from start to 
finish is a luxury that few people get to experience. Finding 
good people to work with (the DTS guys at Apple, StarNine’s 
management team, etc.) made my life a lot easier. 

Dave: As MacHTTP evolved, Apple was spinning their 
own Open Transport I’CP/IP technology. How did you 
deal with tliis? 

Chuck: Open Iransport was probably one of the most painful 
O/S u^ansitions Apple has ever inflicted on its developer 
community, just at the point that MacTCP was becoming well- 
undersuxxl in the develo|:x?r community, widely distributed, 
and pretty much universally supported, along comes O'r. As 
with most examples of not-invented-hcre syndrome, OT was 
based on the mo.stly unsupported STREAMvS interface instead of 
the nearly universally supported Berkeley Sockets interface. So 
not only did developers have to rewrite all their code to u.se 
the new APIs, but they had to learn something from .scralch 
that most of them had never .seen l:x^fore and didn’t really work 
for the first 3 relea.ses. 

OT was definitely a ca.se where it didn’t pay to lx* an early 
adopter. In fact, it was unu.sable for ser\^er applications until its 
third release due to memory lc‘iiks, (xJd timing errors with 
large file transfers, and premature connection terminations. We 
managed to accomexhte it pretty easily once it was debugged 
because WebSTAR was built to our own TCP/IP Al^Is and not 
the lower level O/S specific APIs for MacTCP, OT, or BSD. 
That’s not to say we had our own 'i’CP/IP stack, just that we 
chose to wraj) the low level stuff in some easier to use code. 
'I’hat philosophy was used throughout much of WebSTAR and 
it made it a lot easier to accomodate changes in the O/S than 
other code that was written to the native O/S APIs. 

Dave: What did you have to do to create a real high 
performance server on the Mac OS? 

Chuck: Mo.st well-written .servers turn out to be I/O bound 
a|)plications. They spend most of their time shoving data 
from point A to |)oint B and very little time actually doing 
anything to the data itself. For all the rocks that get thrown 
at it, the Mac O/S can still outperform .servers ainning on 
other platforms like Linux if the code is well-written. One of 


the biggest fallacies is that the Mac’s tasking model is bad 
(not preemptive) and the file system is slow. 1 won’t argue 
the latter point, but the former is totally bogus. 

The Thread Manager is actually a .server developer’s best 
friend if you use it right. 0[)erating .systems like Unix (prior 
to standard implementations of lightweight tlireads) have to 
run parallel threads of execution as separate processes. That 
means heavy-duty context switches and a very crude control 
over task priorities and how control is relinquished. That 
generally equates to poor performance in a multi-threaded 
application with lots of context switches (like a Web seiver). 
On the Mac, the Thread Manager allows for really quick 
context switches that are completely under the control of the 
application. If you know it’s time to handle a new incoming 
connection, your code can yield directly to the ccxle 
responsible. Or if you know you’re waiting on a remote 
client to di.sconnect, you can pass control to another thread 
that is in the middle of a ma.ssive file transfer. Being your 
own scheduler is a good thing if you have a well-understood 
pnxess that you are implementing. Relying on a generic 
O/S-level .scheduler results in pretty lame performance 
compared to a highly-tuned, application-specific .scheduler 
built on a threading environment like the Thread Manager. 

'I’here were two other major areas of optimization that helped 
tune MacHlTP and WebvS'l’AR to the Mac O/S. 'Tlie first was 
data caching. Since it’s costly to find a file in the Mac O/S 
(either to read data from it or to find file .system attributes like 
the creation date), caching this information for future u.se 
provided one of the bigge.st performance increases. In¬ 
memory databa.scs are all the rage now and they are basically 
fancy caching mechanisms much like the ones the.se Web 
.servers iLsed. If you can come up with a good algoritlim for 
managing cache hits, you can end up with a large majority of 
your data requests coming out of memory instead of ratting 
through B-Trees on disk trying to locate Finder info. 

Accomodating the idiosyncracies of tlie Mac’s networking 
code provided the final big performance boost. Simple 
things like double-buffering your data output so that one 
write operation is always awaiting the completion of its 
predecessor ensures that the network connection is 
always fully utilized. Reading data into buffers larger than 
the default sizes makes sure dial you don’t wa.ste a lot of 
CPU cycles processing small amounts of data lots of 
times. Too many context .switches between threads can 
occur if you don’t have the right balance between I/O 
time and calculation/proce.ssing time. Spend more time 
reading or writing data since that takes a lot more time to 
perform than the calculations the server has to perform 
on the data. A lot of this stuff is just common sense, but 
it’s amazing how many developers don’t bother to tune 
their code for best performance after they have the basic 
functionality up and running. 
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Dave: How does an app developer deal with the rich mix 
of connection types and speeds (e.g., slow dial-ups to 
high bandwidth direct connect)? 

Chuck: That’s a big challenge for the next generation of lntemc‘i 
apps. 'Ihe ('iirrent crop of Welo browsers and servers typify the 
one-size-fiLs-all approach to network software development. 
Application perfomiance is metered by the user’s patience level 
and is in direct prop(.)rtion to the available network bandwitli. 
This results in adecjuale [x^rfomiance if you have a large 
network pipe and painfully slow performance if you’re sucking 
data through a 28.8 soda straw. 

Ideally, the data and application performance should 
scale with the performance of the network. A user with a 
28.8 dial-up connection should have application 
performance just as perky as someone using an ADSL 
connection. The way to accomodate this is to write 
smarter software that can .select data appropriate for the 
connection speed and adjust dynamically to changing 
CPU and network loads. Intelligent caching, back-side 
information sharing on the LAN, and distilled content 
(e.g., di.scarding banners, eye candy, and other non- 
informational content) can get just as much useful data 
through a dial-up line as currently flows over a Tl, from 
a ihser’s perspective. 

We’re working on a new generation of desktop network 
applications (super secret codename, “Gossip”, for the 
terminally curious) that takes a shot at implementing 
some of these concepts. We have to very carefully 
monitor the user’s available bandwidth, their usage 
patterns, the types of data they are interested in, and 
adjust the clients’ interaction with the net accordingly. It’s 
hard to write smart .software. I think that’s the next big 
hurdle for developers trying to develop apps for the 
Internet. All the niches for dumb products are filled with 
stuff from Microsoft, Sun, AOL, and other NASDAQ 
luminaries. If you want a piece of this market now, your 
software better do something smart for a change. 

Dave: What advantage do I have as a Mac Develper 
dealing with the web and the internet? 

Chuck: The Mac’s singular advantage over every other platform 
centers around AppleEvents and scripting. And 
unfortunately, it’s one of its most undenitilized and 
underadverti.sed features. Apple birthed a phenomenal 
technology with AppleEvents. I’ve advocated a cross¬ 
platform version of AppleEvents since the day after I read 
that chapter in Inside Mac. Rut until then, the ea.se with 
which complicated Web-based applications can be put 
together on the Mac is unrivaled. Sure, you can muck around 
with active server pages, glom together .some Perl .scripts, or 


hack out .some custom CGIs. Rut nothing available on any 
other O/S rivals the ea.se with which you can h(X)k two 
distributed applications together via AppleEvents. I wish 
Apple would revisit this technology and consider a cross- 
platfonn version that runs over 'LCP/IP. Until then, Mac 
developers can smugly take advantage of a feature that 
doesn’t really exist on any other platform. 

Dave: Wliat are you focused on these days? 

Chuck: I’m back at the helm of RIAP Sy.stems, Inc. We jitst 
finished relocating the company’s main offices from 
Houston, TX to Leesburg, VA and are l)u.sily at work on 
the Next Big Thing (tin). Much of la.st year was spent 
raising money for this exercise and we’re finally getting to 
roll up our sleeves and sling some code again. We’re 
primarily focu.sed on .software that creates communities. 
That’s an outgrowth of .some of the personal server 
concepts we kicked around with MacHTTP and Web.STAR 
as well as the chat .server development we did last year at 
BIAP. It’s all cross-platform stuff this time and we’re 
torturing ounselves with the prospect of getting the same 
chunks of code running on the Mac, Windows, and Linux. 
If you know anybody that wants to help, give us a holler. 

BIBfM 
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by Jeff elites <online@mactech.com> 



Apple surprised everyone when they announced the 
Darwin project, exposing the core of their new operating 
systems for all to see and hack. It is a bold strategy, to try to 
latch onto some of the momentum that is the Linux 
phenomenon. From where 1 sit, I see three possil)Ie outcomes: 
Darwin could form a bridge to lure programmers from the open- 
source community into the Mac fold; It could introduce 
traditional Mac programmers to the larger, traditionally Unix- 
based open-source arena (same bridge, opposite direction of 
travel); or it could flop. It’s too soon to tell which scenario will 
play out. Up until now, the Mac community has not been 
heavily involved in open-source projects, with a few notable 
exceptions. (In fact, the only similar Mac-based community 
project that 1 know of is FilterTop, and most people probably 
have never even heard of it.) I suspect that this is more a 
logi.stical mismatch stemming from underlying design issues 
than a fundamental reflection of the cultures involved. Most 
oj)en-source projects have originated in the Unix world, and 
Unix applications tend to either lack a GUI, being command-line 
and text-configuration-file based, or they have a U1 based on X 
Windows. In either case it would take a considerable amount of 
work to make such applications truly Mac-like, and new 
versions of the core application would have to be re-ported with 
each release. The open-source projects which have successfully 
been brought to the Mac have all surmounted the.se potential 
problems in some way: Linux runs on PowerPC hardware, but 
since it is an entire operating system it isn’t subjects to the 
expectation of a Mac-like design; Mozilla grew out of a product 
which was cro.ss-|)latform before it was open-source, and iLs 
design reflects this; and Perl, Pytlion, and 'Id, the major 
scri|)ting languages, all have Macintosh versions, but as 
programming languages are inherently text-based there is not a 
fundamental design mismatch between platforms. 

Now that Dai*win has arrived and Apple’s operating systems 
are BSD-compatible, Macintosh users are going to have an easier 
time participating in open development projects, or in simply 
using the .software that these projects have already developed. 
Last month we explored resources to help Macintosh developers 
learn more about the Unix world in general. 'Fhis month we are 
going to investigate the of:)en-source phenomenon, with the 
hopes of helping Macintosh developers figure out where they fit 
in the larger scheme. 

Darwin 

<http://www.publicsource.apple.com/> 

FilterTop 

<http://www.topsoft.org/Projects/FilterTop/lndex.html> 


The Open-Source Movement 

The open-source movement is definitely a movement, 
complete with its own interesting characters, terminology, and 
culture. The most influential piece of writing within this 
community is “The Cathedral and the Bazaar”, written by Eric 
Raymond, one of the leaders of the movement and the man who 
started the Open Source Initiative which has actually 
trademarked the term “open source”. You can read about the 
reciuirements that a software license must meet in order for it to 
qualify as open source, and the rationale behind them, at the 
Open Source Page. Another piece of required reading is Open 
Sources: Voices from the Open Source Revolution, a book recently 
made freely available in electronic form by its publisher, O’Reilly 
and Associates. Another site not to be missed is the home of the 
GNU Project and the Free Software Foundation, lead by the other 
mo.st vocal figure of the open-source movement, Richard 
Stallman. This is also where you can read alx)ut the GNU Public 
License (GPL), probably the most common and most restrictive 
open-source license. Finally, you can read more about the history 
and economics of the open-source movement in the online 
version of Tim O’Reilly’s article “The Open-Source Revolution”, 
originally published in Esther Dyson’s expensive Release 1.0 
newsletter. 

The Cathedral and the Bazaar 

<http://www.tuxedo.org/-esr/writings/cathedral-bazaar/> 

The Open Source Page 
<http://opensource.org/> 

Open Sources: Voices from the Open Source Revolution 
<http://www.oreilly.com/catalog/opensources/book/toc.html> 
gnu's Not Unix! - the GNU Project and the Free Software 
Foundation (FSF) <http://wvwv.fsf.org/> 

Release 1.0 —The Open-Source Revolution 
<http://www.edventure.com/release1/1198.html> 

When you are done with these, check out the other links 
available from the MacTech Online web pages at 
<http://www.mactech.com/online/>, and stay tuned for next month, 
when we’ll investigate some open-source projects which could 
benefit from the involvement of the Macintosh community. 
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GAMES 

PROGRAMMING 


By Eric Lengyel 

3D Graphics Engine Essentials 


A crash course on topics that every 3D 
engine designer needs to master 

OVERVlliW 

This year marks the l')eginning of an era in which all 31) 
computer games are requiring hardware acceleration. Using a 31) 
accelerator removers ihe burden of writing a software-based 
triangle rasierizer, but designing a high-quality game engine .still 
requires a lot of work. Iliis article di.sciis.ses how to f)erform and 
efficiently implement ciilculaiions that texlay’s hardware d(x\s not 
handle such as ccxM'dinate transformations, triangle clipping, and 
visibility determination. 1 am going to assume that the reader is 
familiar with the fundamentals of vector and matrix mathematics 
that I use heavily in this article. The bibliography lists a couple of 
sources, including a recent Macl'ech article, which can provide a 
good introduction to this material. 

The intention is to present all of the material in tliis article in a 
platfonn-inde|xmdent manner. It Ls up to the readca- to implement 
any ccxle which is s|xx*ific* to a particular 3D acceleration Aid such 
as OpenGl or Quic:kl)raw31) l^VE. The code accompanying this 
article is general in nature and dexs not depend on any specific API. 
Tlie .staicaires tli;U we will use are shown in listing 1 and include 
generic vector and tnatrix conuiiners as well as stmetures which 
encapsulate vertices and tiiangles. All of the fundions which are 
descril:)ed in this article are implemented as methexLs of the MyEngine 
class .shown in Listing 2. IX'lails alx)ut these staiclures and functions 
are given in the .sections that follow. 

C(K)RDINATF. I'RANSFORMATIONS 

At the lowest level, tlie 3D hardware receives a list of vertices 
and a list of triangles to draw on the screen. Each vertex carries (x, y) 
screen cwrdinates, a z depth value, a c:olor, an alpha value, and 
(w, /;) texture map c(X)rclinates. Each triangle simply indicates which 
tliree memlxis of tlie vertex list seive as its corners. (See the Vertex 
and Triangle .structures shown in Listing 1.) The problem at hand is 
how to Gilctilate where on the screen a given {xoint in 3D space 
should apjxxir for a given camera position and orientation. 

Every 3D engine needs to deal with three different c(X)rdinate 
systems which I will intrcxluce here and discuss in more detail 
shortly. The first is called uk)M space or global space, 'lliis Ls the 
ccx)rdinate system in which everything is absolute, and it’s the 
system in which we specify our ccimera position and tlie position 
of every object in the world. The second coordinate system is called 


object space ox local space. Each objed has its own sfiace in wliich 
the origin corresponds to the position of the object in world space. 
The third ccxxdinate system is called camera space. In camera 
s[)ace, the camera resides at the origin, the xand v^'oordinate axes 
are aligned to the ccxirdinate system of the screen (.v points to the 
right, and y fxiints downward), and the z axis |X)ints in the 
direction that the c'amera Ls facing (and thus the z ccxxdinate in 
camera space represents depth). It should Ix' noted here that many 
3D graphics .sy.stems have the y axis |X)inting upward in c'^tmera 
space, but this results in evil things such as left-handed cxxirdinate 
.systems unless the z axis is also reversed (as Ls the case with 
OpenGL). In any event, it makes life more complicated that It needs 
to lx*, so I will avoid these variants and .stick to what 1 Ixlieve to 
be the more intuitive >Klown .system. 

In order to obtain screen ccxirdinates for a given 3D point, we 
must do two things. Fiist we have to tninsform the point into camera 
space, and then we have to project it onlo the viewing plane which 
represents our .screen. Clipping will take place between the.se two 
operations so tliat we never project ]X)int.s that will not actually 
participate in the final rendering of a sexme. The transformation and 
projection of points is handled ejuite nicely in theory by using four¬ 
dimensional homogeneous coordinates, although in practice we will 
not u.se tlic^se coordinates to tlieir fullest extent for efficiency rettsons. 

Lets Ix'gin with a tran.sfoniiation in noniial 3D coordinates. 
Suppo.se that we had a .scene that contained a single culx^. In the 
culx’s object space, it Ls convenient to place the origin at one of tlie 
comeis and orient the ccx:)rdinate axes to lx‘ parallel witli tlie cube’s 
.sides. We want to lx: able to move tlie culx: anywhere in the .scene 
and to rotate it arbitrarily. Thus, we have to maintain world space 
cxxxdinates for tlie position of the: cube’s origin, and we need to 
maintain a rotation matrix which rcpre.seiiLs the orientation of the 
cube’s kxxil axes in world space. Let us call the cube’s world space 
position P and its rotation matrix M. Then to transform a point A 
from the cubes object space to its global [xisition A^^orkl world 
space, we cxilculate 
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A.,.Hd = MA + P = 
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This Ls tlie object to world or locxil to global tran.sformation. We cxin 
go the other way and tran.sfomi fnim world space to object .space by 
.solving ecjuation (1) for A, which gives us 


Eric Lengyel has recently joined Apple Computer where he Ls working on graphics technology for MacOS X. He can be reached at <lengyeI@a[>ple.com>. 
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( 2 ) 


Note tliat tile columns of die matrix M are simply the vectors 
which correspond to the directions that tlie object’s axes point in 
world space. This is iisefiil since we are going to calculate the 
camera to twrid transfonii just like we would for any other object 
in the scene. I'he camera’s local x, y, and z axes correspond 
resfxjctively to the world space right direction R, down direction 
D, and view direction V of our camera’s configuration, lliis means 
that we tninsform a |X)int from camera space to world 

s[)ace with the equation 


^ world 


K K 

/?, c>. V, 

R. K 

(3) 


A 4- P 

camera camera 


where camera’s world space position. However, we 

will nomially want to traasform points from world space to camera 
space, so the inverse of this transfonn Ls much more useful. If R, D, 
and V are normalized to unit length then the inveise of the rotation 
matrix is just its trans|X)se, whic:h we will call C, and the world to 
camera transfoniiation is given by 


A = C(\ - P ) = 

camera woiicl camera' 


K 

(4) 


V, 
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When we are projecting vertices from a triangle mesh onto the 
screen, we never need to know die actual world space cxxirdinales 
of each vertex. We can transform directly from object space to 
aimera space by coiiijxxsing die object to world and world to 
camera transformations as follows. 


= C( MA + P - P_) = (CM)A -f C(P - P_) 

(5) 

Perfonning transfonnations in this manner is tedious since we 
need to use lx)di of the matricc^s C and M, and we have to perform 
iwo matrix-vector mtiltiplies. Tlie problem is further ciompounded if 
a hierarchical scene is being utilized in which objects may have sub¬ 
objects wliich have their own i(x:al ccxirdinate spaces, thus requiring 
additional steps to transform from sulxobjecl space to camera space. 

Fortunately, there is a more compact and elegant meth<xl for 
handling these transfonnations. It turns out that we can use die 
previously mentioned homogeneous ccxirdinates, and in die prcx'css 
we can combine the 3x3 rotation matrix and transladon vector 
needed in die transfonnations that we have been working widi so 
far into a single 4x4 matrix. This simplifies the conipcxsition 
operation since all we have to do multiply the matrices 
corres|X)nding to c‘ac:h transformation togedier. 

Fii*st, the definition of homogeneous ccxirdinates is necessary. 
A homogeneous point P is represented by four c(X)rdinates: 


P = w^O 


( 6 ) 


Tlie corresjxinding diree-dimensional point P^ is obtained by 
dividing each ccxirdinate by w and disc-iirding the fourth ccxirdiruite 
(whic h always becomes 1): 

P3D =(a:/w,y/w,z/w) 

(7) 

A 3D jxiint with ccxirdinates (x, y z) CAn lx* represented in 
homogencxxis ccxirdinates by (x, y z, 1). This givc-s us a four- 
climeasional vector whic:h c^n be operated on by four-dimensional 
matrices. In fact, as will lx demonstrated later, the projection of a 
point onto the view plane can be |X*rforniecl by using a 4x4 matrix 
that mexJifies the fourth cxxxdinate of a vector. 

Referring back to the 3x3 rotation matrix M and world space 
position P from the object to world transformation in eciuation (1), 
we see that we c:an prcxltice the Siiiiie transformation with a 4x4 
matrix having die fonn. 






W.0 








0 

0 

0 
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(8) 




Multiplying this matrix by a point A = (yl^, A^„ 1) yields the 

.same re.sult as multiplying M by and then adding P. An 
important fact is that the fourth ccxirdinate of A remains 1 when 
multiplied by a matrix of the form shown in equation (8). 
Additionally, when two matrices of this form are multiplied 
together, die fourth row of the product is always (0, 0, 0, 1). This 
iiifoniiation will allow us to make some optimizations when we 
implement the calculations. 

Using the notation from equation (4), the world to camera 
transform can lx: accomplished in homogeneous ccxirdinates by 
using the matrix. 

T = /X D, 

0 0 0 1 

(9) 

The product gives us a single 4x4 matrix which 

tran.sforms points from object space directly into camera space. This 
[ircxJuct only h^Ls to lie calculated once foi’ each object, and it 
replaces the relatively messy eejuation (5). 

Most 3D acceleration AI^Fs rexjuire that the z-c(X)ixiinate of a 
vertex in camera space be in the range 0.0 to 1.0. (Tlie Glide API Ls 
an exception to this convention.) This nieaas that we have to scale 
everything in die z direction so that 1.0 represents the furthest 
distance that anything in the scene will Ix^ fixiiii die camera. Calling 
diis distance z^^^, we can include the scale in the world to camera 
transformation by using die matrix. 
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Tracks 


• strategy 

• information 
design 

• visual design 

• usability 

• programming 

• backend 


June 27 - July 1 
Moscone Center 
San Francisco 

Contact us today for 
information on the 
conference offerings 
and how to register. 

wv^vy/.mfv^eb.com 

phone 

(800) 441-8826 

email 

web99@mfi.com 
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In June 1999, hundreds of web 
teams from around the world will 
pack their bags and travel, any way 
they can, to Web Design & 
Development — WEB99. 

In '96 we took you beyond static 
pages. In '97 we showed teams 
how to work together to build sites, 
filtering through the profusion of 
new technologies and techniques. In 
'98 we highlighted site usability and 
customer focus. 


In '99 it's still about all of this — 
and much more. Collaborative team 
building. Leveraging technology and 
streamlining processes. Keeping the 
market share you've fought for. 

Going beyond the buzzwords. And, 
as always, creating meaningful sites 
for customers. 

Learn from industry veterans and 
acclaimed educators in more than 
100 classes and tutorials. Keynotes, 
panels and parties provide more ways 


to learn, commune and further your 
career. Check out all the details at 
www.mfweb.com. 

If you're dedicated to the medium, 
you’ll see exactly how WEB99 is 
dedicated to you and your entire 
team. Get there. 





Miller Freeman 
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0 0 0 1 

( 10 ) 

Tills is the final world to aimera tnmsfoimation that needs to lx‘ 
calculated whenever the ciimera position or orientation changes 
(which may lx? for every frame). 

Now that we are able to transfonn our vertices into ciunera 
sjyace, wc need to discuss the method used to project them onto tlic 
view plane. We fii'st need to chcx>se the distance from the camera to 
the view plane. Shorter view plane distances result in wider fields of 
view. As shown in Figure 1, the screen is represented by a rectangle 
on the view plane whose JC-C(X)rdinate ranges from -1.0 to 1.0 and 
who.se v-coordinate ranges from -h to h, where h is tlie height to 
widlli ratio {h = 0.75 for a 640x480 display). For a desired horizontal 
field of view angle q, the view plane di.stance d is given by. 


^max tan(6>/2) 

( 11 ) 

A point which has already been transformed into camera 
space can be projected onto the view plane through 
multiplication by the matrix. 

“ I 0 0 O’ 

0 1 0 0 
0 0 10 
0 0 Md 0 

( 12 ) 

This matrix transfomis a jX)int Q = (x, )\ z 1) into the fxiini QC = 
(x, }\ z, z/d). When we divide by tlie w comjxment, w = z/d, we 
obtain the 31) ix)int, 



(13) 

which lies in the view plane. Of course, in the real world we don’t 
ncx?d to |X*rform the matrix multipliaition, but this d(xs demoastrate 
that all we need to do in order to [:)r()ject a point onto the view plane 
is Gilculate \/tv = dJz, 


(1, Ik cl) 



Figure 1. Camera Space arid View Plane ConJi^uralUm. 


Once we have multiplied the jcand y components of a point 
by l/w, we have rcxsolution-independent view plane coordinates. 
To obtain actual screen coordinates, we need to .scale the x value 
from the range [-1.0, 1.0] to the range 10, Vklrhl v value 

from die range [-/?, h] to the range [0, where Vidth 

height dimensions of die display in pixels. This is 

accomplished through the equadons 

^ _ ‘^widlh y I *^widtli 

'^screen 2 '^view ' ^ 

and 

^ _ ^^width . '^height 

.screen 2 ^ 

(14) ami (15) 

The implementation details for the transformation and 
projection of vertices are summtirized by the steps below. The 
TransformVertices function shown in Listing 3 traasforms an array of 
vertices from object space to camera space and temporarily stores 
them in a private array of the MyEngine class where they are used 
during the clipping pha.se. 

1. Calculate the world to camera tran.sformation matrix 

given by equation (10). Tlie fourth row of this matrix is always 
(0, 0, 0,1), so it may be suppre,s.secl for efficiency. As done with 
the Matrix4D .structure shown in Listing 1, we can consider it to 
be a 3x4 matrix that behaves like a 4x4 matrix. 

2. For a given object in the .scene, calculate the matrix product 
^carnera'^world’ where 'I\v()rld object to world transformation. 
Again, the fourdi rows of lhe.se matric'es may be ignored since 
they will always lx (0, 0, 0, 1). 

3. For ejich vertex V belonging to the objext, transfonn die |xiint 

from object spacx? to camera space by calc'ulating = 

tiitrra^worid^' Once again, there is no ncxd to use the fourth 
ccxirdinate of the vector V. 

4. Clip all of the triangles Ixlonging to the object (sex the section 
entidcxl “"Clipping”). 

5. For each vertex V that was tran.sfc)nnc*cl in step 3, calculate 
l/w'= djV^ ScTeen ccx)rdinate.s are given by equations (14) and 
(15) where = K/wrand = k'///;. 

6. Fa.ss the values A;;creeiv Tscreen» 

acceleration API. (In QuickDraw 3D HAVE, these values 
correspond to the x, y, z, and invW fields of the TQAVGouraud 
and TQAVTexture structures.) 

7. Repeat .steps 2-6 for each object in the .scene which Ls |X)tcntially 
visible (see the section entitled “Visibility Deteniiination”). 

Listing 1: Useftil structures 

Veaor3D 

This jitructure Ls ased to hold a 30 point or a diixxtion vector OpcTators arc 
overloaded Ibr addition, subtraction, scalar miiitiplicntion, and the dot pioduci. 

struct Vector3D 
( 

float X, y, z; 

Vector3D() 0 

Vector3D(float r, float s. float l) 

( 

X = r; y = s; z = t; 
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Veclor3D operator +(const Veclor3D& v) const 
return (Vcctor3D(x + v.x. y + v.y, 7. + v.z)); 
VectorSD operator (const Vector3D& v) consL 
return (Vector3D(x v.x, y - v.y. z - v.z)); 

1 

\/ecLor3D operator ‘(float f) con.st 

I 

return (VGctor3D(x * f. y * f. z * f)): 


//1>()1 prodiia 

float operator ‘(const Vector3D& v) const 
return (x * v.x + y * v.y + z * v.z): 

) 

I: 


M;Urix4D 

This stniclua' is used to hold a 4x4 traasfonniiiion matrix whose ftturih n)w is always 
((),(),(), 1). Multiplication operators are ovcrl(xided for tlic matrix-vector product ;ind 
the miUrix-malrix pnxluct.Thc Inuerse lunction calculates the* inve-rse of a matrix. 

struct Matrix4D 

I 

float n[4][3]; 

Matrix4D() () 

Matrix4D(float nOO, float nOl, float n02. float n03. 
float nlO. float nil, float nl2. float n13. 
float n20, float n21. float n22, float n23) 

^ n[0l[0l = nOO; nil] [O] = nOl; n[2l[0] = n02: 

n[3][0] = n03; n[0j[lj = iilO: n[l][ll =011: 

n[2][]] - nl2; n[3]llj = nl3; n[0](2l = n20: 

nil] [2] - n21; nf2l[2j = n22; nl3] [2] = n23; 

} 


Vector3D operator ‘(con.st VGctor3D& v) const; 
MatrixAD operator ‘(const Matrix4D& m) const: 


// Matrix-vex tor pitxluct 
Vector3D Malrix4D:loperator 
I 

return (Vector3D( n[0] lO] 
n[2] [0] 
nlO](l] 
nUJll] 
nlOjU] 
n(2]l2j 

1 


‘(const VGCtor3D& v) const 

* v.x + nil]lO] • v.y + 

‘ v.z + nt3] lOj , 

* v.x I nil] tlj ‘ v.y 

* v.z + nfS] ll]. 

* v.x n[l] [2] ‘ v.y + 

* v.z + n [3] [2])): 


// Matrix-matrix pnxluct 

Matrix4D Matrix4D:: opera tor ‘(const Matrix4DSf m) con.st 


iturn (Matrix4D( 


n[l][0] 


m.nlO]ll] 


n(0l[0] 

* 

m.nlO]lOj 

+ 

‘ 

-p 

nl2][0] 


m.nlO][2], 




m.nll] [1] 


nlO] [0] 

* 

m.nll] fO] 

-P 

nlUlO] 

* 

p 

n[2] [0] 

* 

m.nll] [2] , 




in.nt2] [1] 


ntOjlO] 

* 

m.nt2][0] 

1 

nriiioj 

* 

-p 

n[2][0j 

* 

m.n [2] 12] , 




m.nL3j ll] 


nfOl [0] 

* 

m.n[3] [0] 

-P 

n[1][0l 

* 

-p 

n[2U0l 

* 

m.nl3] [2] 

+ 

i.[3][0l. 


m.nfo]ll] 


n(0] [1] 


m.nlOj lOj 

+ 

n[l][ll 


-p 

ii[2)[l] 

♦ 

m.nfo][2], 




m.nll][1] 


n[0) [1] 

* 

m.nll] fO] 

-h 

nllj[l] 

• 

+ 

nl2][l] 

* 

m.n[l][2] 




m.nt2] [1] 


nlOJlU 

* 

ra.n[2] [0] 

’ f 

n[l][l] 

* 

-p 

n[2]llj 

* 

m.n[2] [2] 




m.nl3] ll] 


nfOl[1] 

* 

m.n[3] to] 


nturil 

* 

+ 

n[ 2 lfn 

♦ 

m.nL3] [2] 

+ 

n[3][l] 


m.nlO] ll] 


n[0](2l 


m.nlOj lO] 

+ 

n[l][2] 

* 

+ 

11 [2] [2] 


m.nlO]l2j 




m.nll] [1] 


ii[0] [2] 

* 

m.nll] fo] 


nil] [2] 

* 

1 

n[2][2] 

* 

m.nll][2] 

, 



m.n[2] ll] 


nlO] [2] 

‘ 

m.n12][0] 


nil]12] 

* 

-p 

nl2j 12] 

* 

m.n12][2] 

, 



in.nl3] ll] 


n[0l[2] 

* 

m.nt3][0] 

-P 

n[ll[2l 

« 

+ 

n[2l [21 

* 

m.nl3j l2] 

-P 

n[3] [2])) 




1 


Matrix4U Inverse(const Matrix4D& m) 

I 

float nOO = Hi.nlO] [0] ; 
float nOl = m.nll] [O] ; 
float n02 = ni.n(2] [0] ; 
float X = m.n [3J lO] : 
float nlO = m.nlOj Ll]: 
float nil =m.nll]llj: 
float nl2 = m.nf2l ll] : 
float y = ni.n[3] 111 : 
float n20 = ui.ntO] [2] ; 
float n21 = m.nll] [2] ; 
float n22 - m.nl2] 12] ; 
float z = m.nl3jl2] : 
float t = l.OF / (nOO ‘ (nil * n22 


nOl 

n02 


(nlO 

(nlO 


n22 

n21 


nl2 

nil 


return (Matrlx4D( 


n20) + 
ri20)): 


(nil * 

n22 

nl2 * 

n21) * 

t. 


(n02 • 

n21 

nOl ‘ 

n22) * 

t. 


(nOl * 

nl2 - 

n02 * 

nil) • 

t, 


((nl2 • 

n21 - 

nil * 

n22) • 

’ X 

+ 

(nOl 

‘ n22 

- n02 

• n2l) 

* 

y + 

(n02 

* nil 

- nOl 

‘ nl2) 

* 

7 ) * 

(!i12 * 

n20 - 

nlO * 

n22) * 

L, 


(nOO • 

n22. - 

n02 ‘ 

n20) • 

t. 


(n02 * 

nlO 

nOO * 

nl2) * 

t. 


((nlO • 

' n22 

nl2. ‘ 

' n20) ' 

‘ X 

+ 

(n02 

* n20 

- nOO 

* n22) 

* 

y + 

(nOO 

* nl2 

- n02 

* nlO) 

* 

z) ‘ 

(nlO * 

n21 - 

nil * 

n20) * 

t, 


(nOI * 

n20 - 

nOO ‘ 

ri21) * 

T , 


(nOO * 

nil - 

nOl * 

nlO) ■ 

L, 


((nil ' 

' n20 ■ 

nlO ‘ 

' n21) ' 

• X 

-p 

(nOO 

‘ n21 

- nOl 

• n20) 

• 

y + 

(nOl 

‘ nlO 

nOO 

• nil) 

* 

z) * 


nl2 ‘ n21) 


t)); 


Vertex 


Tliis stiiKture contains all of the infi)rmation that is associated with a single vertex, 
struct Vertex 


VectorlD 

float 

float 

float 


point; 

red. green, blue; 

alpha; 

u, v; 


// Position 
// Diffuse color 
//TranspareiK 7 
//Texture mapping 


Iriimgle 

'lliis siruclure* contains all of the information tltit is associated with a single triangle. 


struct Triangle 

( 

1 ong index 13 ] : // Indexes into vertex iuray 

Vee Lor3D normal: // Surface normal 

I; 

.Mesh 

This struciure contains an array of vertices and an array of triangles which compose a 
single mcsltilie objectToUJorldTransform matrix dcfinc*s the mesh's position 
and oricntiition as given by cqiuition (8).The bounding sphere information is used for 
visibility determimition. 


struct Mesh 
1 

long 

long 

Vertex 

Triangle 

Matrix4D 

Vcctor3D 

float 


VC rt exCount: // NumbcT of vertices in mesh 

triangl eCoimt; // Number of triangles in mesh 

*vertexAr ray; // Pointer to vertex array 

* triangl eAr ray; // Pointer to triangle array 

objectToWorldTransform; 
boundingSphereCenter; 
boimdingSphereRadius; 


Listing 2: Engine class 

iMylingine 

The MyEngine class encapsulates information al>out die camera configuration ;md 
holds pointers to storage for transformed vertices and clipixxl triangles.Tlie tiinetions 
which perft)rm coordinate minsformations, triangle dipping, and visibility 
ddexmination arc implemented as nuxhtxls of this class. 
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class MyEngine 

\ 


//Worid space 
// Should be unit length 
// Should be luiii lengUi 
// Should be luiii lengtli 


private: 

// Maximum z r.ilue 
float maxDepth; 

// Distanee from camera to view plane 
float viewPlaneDlstance: 

// Heiglu to width ratio of the screen 
float heightOverWidth; 

// Camera contiguration 
Vector3D cameraPosition: 

Vector3D rightDirection; 

Vector3D downDirection; 

Vector3D viewDirection; 

//Tninsfomtuion from world space to camera space 
Matrix4D worldToCameraTraiisforra; 

//World space side plane normals (used for boimding sphere test) 

Vector3D leftPlancNoraal; 

Vector3D rightPlaneNormal; 

Vector3D topPlaneNormal; 

Vector3D bottomPianeNormal; 

// Number of tnuisfomied vertices in tlie vertex array 
long vertexCount; 

// Numlxr of elipfxd triangles in the triangle array 
long triangleCouriL; 

// lfrcall(x*atc*d storage for vcTtiees and uiangles 
Vertex *vcriexArray; 

Triangle *triangleArray; 

//Vertex intcT{X)lation function used for clipping 
static void InterpolateVertices(const Vertex *vl, 
const Vertex *v2, float t. Vertex ‘newVertex); 
public: 

MyEngine(); 

~MyEngine(); 

// (iillcxl before any midcring c“aleuIations (details below) 
void PrepareToRender(void); 

// IXtennine if a mesh's lx)unding sphnx* is visible 

bool SphereVisible(const VGctor3D& woridCenter. 

float radius, long •clipFlags): 

//'Ihiiislbrm vertices to camera space 
void TransformVorLiees(iong count, 
con.^it VerLox ‘vertex, 
const Matrix4D& objectToWorldTransforra); 

// Clip truingles lo view Ihistum 

void ClipTriangle(const Triangle ‘triangle, 
long clipFlags); 

// IX) eveittliing ncx:ess;ir)' lo render a mesh 
void RenderMesh(const Mesh *mesh); 


MyEnginc::MyEngine() 

//Allcxtiie vcTlex :ind trumgle arrav’s. CTioosc die consents kMaxVertiees and 
// kM:ix rrianglc*s so that these arrays are large cnougli to hold tlie kiigesi single 
// iiKtsh Uut will be renderexl. Ik- sure lo indude space for extra vcniees and 
// lri;ingles that may be cTe;iied during the dipping pnoc'css. 
vertexArray “ new Vertex[kMaxVertiees] : 
trianglcArray = new Triangle[kMaxTrianglesj: 


MyEngine::-MyEngine() 

( 

delete[1 trianglcArray: 
delete[1 vertexArray; 


worldToCameraTransform.nfl][2] " 
viewDirection.y * recipMaxDepth; 
worldToCaineraTransforin.n[2] [2] = 
viewDirection.z * recipMaxDepth; 
float X = cajneraPositlon.x; 
float y = cameraPosition.y; 
float z = cameraPosition.z; 
worldToCameraTransform.n[3][0] = 

-worldToCameraTransfonn.nfOl f0]‘x- 
worldToCameraTransform.n[l][0] ‘ y 
worldToCameraTransform.n[2][0] * z: 
worldToCameraTransform.n[3][1] = 

-worldToCameraTransform.n[Oj [Ij *x- 
worldToCameraTransform.n[1j [1] * y - 
worldToCameraTransform.n[2] flj * z: 
worldToCameraTransform.n[3][2] = 
-worldToCameraTransforra.n[Ol [2] * x 
worldToCameraTransform.nfl][2] * y 
worldToCameraTransform.n[2] [2] * z; 

// Compute unit-lengdi normal vectors for the four side phuicti. 
//Tliese arc used by the SphereVisible fruieiion. 
float f = vlewPlaneDistance * maxDepth: 
float h = heightOverWidth; 

// See the sidebar “Rist Sqiuue R(H)ls’'f(>r the RS(|rt hineiion. 
float gl = RSqrtd.OF -t f * f); 
float g2 = RSqrt(h * h » f * f); 
leftPlaneNormal = 

(viewDirection 1 rightDirection * f) * gl; 
rightPlaneNormal “ 

(viewDirection rightDirection * f) ‘ gl; 
topPlaneNormal = 

(viewDirection * h + downDirection * f) ‘ g2: 
bottomPianeNormal - 

(viewDirection * h - downDirection * f) * g2: 


Listing 3: Vertex transformation 

TransformVerticcs 

This liinclion transforms :in array of vertices from :m object’s loc-Jil space into cuuera 
space. Rich vertex’s color, iranspareiiey.and mapping is simply copied lo the array of 
transformed vertices here.hul the routine could lx- modified so that a translation to 
the native vertex format of the 31) acceleration AIM being ii.sc-cl is performed. 

void MyEngine:iTransforniVertices(long count, 
const Vertex *vertex, 

^ const Matrix4D6t objectToWorldTransform) 

vertexCount = count: 

// (aleukite object to ttmiera traasform. 

Matrix4U m = worldToCameraTransform ‘ 
obj ectToWorIdTransfo rm; 

//Transformed vertices get placed in private array. 

Vertex ‘v = vertexArray: 

for (long a 0: a < count; a++) 

I 

//Transft)rm vertex into camera space. 
v->point = m * vertex->point: 

V >red = vertex->red; 

V >green ^ vertex->green; 
v->blue = vertex->bluc: 
v->alpha = vertex >alpha: 
v->u = vertex >u: 

v->v vertex->v: 


Prepare-roRender 

'fliis hinetion eonif)utes the world to c-amc-ni transformation matrix and the world 
sixiee noniKil vectors for the four side planes of the view frustum. It should lx- called 
once for cadi rendered frame Ix-ftire- any RenderMesh calls are rruide. 

void MyEnginc::PrepareToRender(void) 

1 

float recipMaxDepth l.OF / maxDepth; 

// (x>mpute worid to cimera tnin.sformaiion. See equation (10). 
worldToCameraTransform.n[0] [Oj = rightDirection.x; 
worldToCameraTransfonn.n[ij [Oj = rightDi rectiori.y; 
worldToCameraTransform.n[2] [0] = rightDirection.z: 
WorldToCameraTransform.n[0] [1] = downDirection.x; 
worldToCameraTransform.n[ll [l] = downDirection.y: 
worldToCameraTransform.n[2] [I] = downDirection.z; 
worldToCameraTransform.n[0][2] = 
viewDirection.X * recipMaxDepth; 


V-H-; 

vertex+-l-; 

) 

) 


Clipping 

Figure 2 illustrates the tiew frustum, the volume of space 
shapexi like a tninc'atecl pyramid whexse afx.‘x lies at tlie cTimera 
pcTsition, tliat coincidc*s with the ex:ict visible region for a given 
oamera configuration. Tlie view fnistum Ls com|Xxsed of four side 
planes which piss through the cTimera pxsiiion, the /row/ plane ox 
near plane is usually placed at z= c/(c/lx*ing the view plane 
distance from the previous section), and the hack plane ox far plane 
wliich is placed at z= 1.0. 
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E\st Square Roai^ 

The square root and the reciprocal of a square rcxa arc operations 
which arise freqiienily in 31^ programming. For example, ilie 
noi'malixation of a vector V = (x, y, z) requires thal we divide by the 
square root of -t + z^. Fortunately, there is an extremely fast metlicxl 
for computing botli of tliese (juanuties using Neivton's Metf.xxl, which Ls 
derived here. 

Suppose we need to find the rfx)t of the function /jc) shown in the 
figure below. Our goal is to approximate the value of x for which 
/.v) = 0. Let us make an initial guess for tliis value of xand call it Xj. If 
we evaluate tlie hinctiony at Xj and its derivative y'c at X|, then we have 
a tangent line which is defined by the ]X)int (X}, /xp) and the slope 
/CCxj). The equation for tliis line Is 

.v-/(a',) = /<x,)(a- X,) 

(A) 

Notice that this line intersects the x-axis at a [X)ini which is much closer 
to die actual root of/.x) tlian our original guess x^. Solving cxjuation (A) 
for X when y - 0 gives us the refinement equation 


(B) 

Each time this ecjuation is iterated, we obtain a new value of x which is 
closer to the root of/x) that we wish to find. 



We determine die refinement ecjuation for a recipr(x:al square root by 
using the flmaion 

/(x) = X"" - ri 
(C) 

since its roots are given by 



(D) 

Plugging this function into cx^uation (B) gives us 

X," ^ - n 
Xy = X,-*-^ 

-2^r 

= ^x,(2- n.Kf). 

(E) 


Tliis itemlion allows us to ciuickly converge on the reciproail square root 
of a number ri We can find die square root itself dirough one additional 
multiplication; 

■\fn 

CF) 

Where do we get our initial guess? How^ many iteraiioas do we 
have to perform? Luckily, eveiy PowerPC processor, widi the exception 
of the 601, h;is an instruction called Floating Reciprocal Square Root 
Estimate (frsqrte) whicli givc;s an approximation to a recifirocal scjiiare 
rcx)t wdth five bits of jirccision. (This instniction is accessible from C 
ihrough the intrinsic hinction _ frsqrte.) Ii turns out that two iterations of 
equation (E) give exact single precision (32-bit) results for aliiKxst all 
values of n. Tlie alxive rneilKKl for finding a reciprocal square root is 
implemented in the RSqrt function shown Ix’low. 

inlint? flo^t XSqrt(afloat n)" 

f ‘ ::: 

// Gel initial estimate 
float X = f ; 

// Apply refinement step twice 

' _ m 



Figutv 2, The Vieir Tntslum. 

After the three vertices ii.sed by a particular triangle have 
In'cn transforniecl into camera space, there are three 
po.ssibililies. The first is that all three vertices lie inside the 
view frustum. In this ca.se, we say that the triangle is trivially 
accepted and pa.ss it on unaltered lo lie rendered. The second 
po.ssibility is that all three vertices lie outside the view fru.stum. 
When this luqipcn.s, we .say that the triangle is trivially rejected 
and do not consider it any further for rendering. The 
remaining possibility is that some of the vertices lie inside the 
view frustum and the rest lie outside. For this case, the triangle 
must be clipped into one or two smaller triangles which do lie 
completely inside the view frustum. 

For each triangle, clipping occurs in camera space one 
plane at a time. If it is known that everything in the vScenc is 
within the distance from the camera, then it is safe to 
ignore the back plane. For each plane, we consider the side 
facing the view frustum to be the positive side, and the side 
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Facing away to be the negative side. Thus a point is inside 
the view frustum if and only if it does not lie on the negative 
side of any of the six planes. A point lying exactly on one of 
the planes is still considered to be inside the view frustum. 

For a given clipping plane, we need to classify the three 
vertices of a triangle as either lying on the positive side of the 
plane (which for our purposes includes vertices that lie exactly 
on the plane) or lying on the negative side of the plane. If it 
is ever the case that all three vertices lie on ihe negative side 
of any plane, then the triangle should be immediately 
discarded because it is not visible. If all three vertices lie on 
the positive side of the plane, then no clipping needs to occur 
for that plane and the triangle should be passed on to be 
checked against the other clipping f)lanes. The remaining iwo 
possibilities are illustraied in Figure 3- If two vertices lie on 
the negative side of the plane, then the triangle needs to be 
clipped to coincide with the par! of its area which lies on the 
positive side of the plane. If only one vertex lies on the 
negative side of the plane, then the polygon corresponding to 
the area lying on the positive side of the plane is a 
(juadrilateral, and thus needs to be .split into two triangles. 

Nonna! 



The meth(xi by which w^e classify vertices as lying on the 
positive or negative side of a clipping plane dejx^nds on which 
plane we are considering. For tlie front and Irack planes, we 
simply compare the z coordinate of a vertex to the distance 
separating ilie plane from the camera. Thus a vertex lies on the 
p(xsiiive side of the front plane if z> d, and a vertex lies on the 
positive side of the back plane if z< TO. For the remaining four 
side planes, we can determine the location of a vertex relative to 
one of die planes by calculating die dot product between the 
vertex position and the plane’s normal vector. A negative dot 
product indicates that the point lies on the negative side of the 
plane. The table below lists the inward-facing normal vectors for 
each plane of the view frustum where d is die view plane distance 
and h is the height to width ratio of the .screen. 

Plane Normal 

Front (0,0,1) 

Rack (0, 0, -1) 

Left (d,0, 1) 

Right (-k1, 0, 1) 

Top (0, d, h) 

Bottom (0, -d, h) 


After determining that a triangle is split by a clipping plane (by 
observing that one or two vertices lie on the negative side of die 
plane), we must find the actual points of intersection along die 
tiiangle’s edges. The.se points will .serve as die veitices for the 
clipped !riangle(s). The line segment connecting two vertices V| and 
V 2 can lx? descrilxxl by the fxirametric equation 

P(/) = V,+r(V2-V,) 

( 16 ) 

where / ranges from 0.0 to 1.0. A plane is descrilx?d by the ecjuation 

N P-D = 0 

(17) 

where N is the plane’s normal vector and D is the di.stance 
from the origin to the plane along the direction of N. To 
determine at what value of / a line .segment intersects a plane, 
we substitute the function P(/) from equation (16) for P in 
equation (17). This gives us. 

N[V, +r(V2-V,)]-D = 0 

(18) 

Solving diis equation for /, we obtain. 

D-N>V , 

N-V2-N~-V, 

(19) 

The value of D is the view plane distance d for the front jilane, 1.0 
for the back plane, and 0.0 for die side planes since they pass 
through the camera space origin. Once the value of / has lx.‘en 
calculated, we simply plug it into equation (16) to obtain the 
interpolated vertex pcxsition. 

When implementing vertex inicqxilation for a clipping 
function, it is very important to consistently chocxse which vertex 
is to be V) and which vertex is to be V 2 for e(|ualion (19). Consider 
the case when there are two adjac:enl triangles which share an 
edge that intei:seas one of the clipping planes. If, when die first 
triangle is clipped, V| is chosen to be the vertex lying on the 
positiwsklc of die plane, and when the second triangle is clipped, 
Vj is cluxsen to lie the vertex lying on the negatiw side of die 
yilane, the resulting values of / may not be exactly the same due to 
different floating yxiint round-off errors. This would cause the 
interpolated vertex for the first triangle to be slighdy misaligned 
with the interpolated vertex for die second triangle, po.ssibly 
aiusing visible artifacts along the clipped edge. 

The ClipTriangle function shown in Listing 4 demonstrates a 
gcxxl triangle clipping implementadon. When the function ncx?ds to 
interpolate vertices, it always chooses the vertex lying on the 
negative side of a clipping plane as V| for the applic:ation of 
ecjuaiion (19). llie clipFlags ]:)arameter indicates to the clipping 
function which planes actually need to be considered. The next 
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section descrilxjs a metlicxi for selecting its initial value. Any triangle 
tliiit Ls created during the clipping process is recursively clipped 
using a value for dipFlags which excludes any planes agaiasl which 
its corre.sponding origiruti triangle lias already been clipped. 


Listing 4:1 riangle clipping 


InterpoLitcVcrticcs 

Tliis routine pnxJutes a new vertex whose position, colon transparency, and texture 
mapping c(K)Rliniites are the a^sult of interpolating between two givni vertices using 
a given parameter /, when* 0.0 < / < 1.0. 

void MyEngine:ilnterpoiateVertices(const Vertex •vl, 

^ const Vertex *v2, float t. Vertex *newVertex) 

newVertex->point.x = vl->point.x + 
t * (v2->point.x vl->point.x); 
newVertGx->point.y = vl->point.y + 
t * (v2->poinL.y - vl->point.y); 
newVertex->poinL.z = vl->point.z f 
t * (v2 >point.z - vl->point.z); 
newVerlGx >red = vl*>red + t * (v2 >red - vl->red); 
ncwVGrtex->green “ vl->green + t * (v2->green - vl->grccn): 
newVertex*>bluG = vl->blue + t * (v2->blue - vl->blue); 
newVertex->alpha = vl >alpha + t * (v2->alpha vl >alpha); 
newVGrtex->u = vl >u + t * (v2->u - vl->u); 
newVertex->v * vl >v + t * {v2->v - vl->v); 


('.lipTriangle 

Tills routine elips a given triangle to the* view fnisium. It Is iLssumed that all iliree 
vertiees aa* closer to the camera than the back plane.Tlie resulting t lipped iriangle(s) 
aix* added to the triangle amiy |x)inied to by MyEngineiltrlangleRrray.'llie 
ClipFlags parameter is a eombinaiion of the Ibllowing bit flags, wliich indicate 
which planes need to lx- considered for the triangle. 

con.st long clipFlagNone = 0; 
const long clipFlagFront 1; 
const long clipFlagBack = 2; 
const long clipFlagLeft = 4: 
const long clipFlagRight = 8: 
const long clipFlagTop = 16: 
coHvSt long clipFlagBottom = 32: 
const long clipFlagAll = 63; 

void MyKngine::ClipTrianglc(const Triangle ‘triangle. 

long clipFlags) 

I 

Triangle t; 

float d = viowPlaneDistance: 

float h heightOverWidth; 

long il = triangle->index[0]: 

long i 2 = trianglG->index[1] ; 

long i3 = triangle->indGx[2] ; 

const Vertex *vl = &vertexArrayLil]; 

const Vertex •v2 &vertexArrayLi2] : 

const Vertex ‘v3 = fitvertexArrayfiSl : 

if (clipFlags St clipFlagFront) //Clipagjiiasi front plane. 

long bl = (vl*>point.z < d) ; //Vertex 1 on negative .side? 

long b2 = (v2->point.z < d) : //Vertex 2 on negative .side? 

long b3 - (v3*>poinL.z < d) ; //Vertex 3 on negjitive side? 

// (a)uril number of vertices on negative side of plane, 
long b = bl f b2 + b3: 
if (b != 0) 

{ 

i r (b = 1) // One vertex Is on the negative side. 

( // Find out which one it is. 

if (bl) 

( 

// Chop original titingic down to a smaller quadrilatenil. Mtxlify 
// the origiruil triangle to serve as one half of the qmd ;uid create 
// a new titinglc to fill in the other half 
i1 = vertexCount+i: 
long i = vGrtexCount++; 

Vertex *v = &vertcxArray[ilJ: 
lnterpolateVertlces(vl. v2. U - vl->polnt.z) / 
(v2->point.z vl->point.z), v): 
InterpolatcVGrtices(vl. v3. (d - vl >point.z) / 
(v3->point.z - vl->point.7.). ifvertexArray [il) ; 


t.index[0] = i; 
t.index[1] ^ 11; 
t.index[2] = i3; 
vl = v; 


else if (b2) 
{ 


12 = vertexCount-H-; 
long i = vertexCount++: 

Vertex ‘v = &vertexArray[i2l ; 
IntGrpolateVertices(v2, v3. (d 

(v3->point.z - v2->point. 7 .), 
TnterpolateVerticGs(v2. vl. (d 
(vl->point.z - v2->point.z), 
t.index[0] = il; 
t.index[1] = i; 
t.index[21 =12; 
v2 = v; 

} 

else 

I 

13 = vertexCount-H-; 
long i = vertexCount-H-; 

Vertex *v = &vericxArray[i3j: 
InterpolateVertices(v3, vl. (d 

(vl->point.z - v3->point.z). 
Interpol aLeVertices(v3. v2. (d 
(v2 >point.z - v3*>point.2). 
L.index[Oj i3; 

1. index [Ij - i2: 
t.index[2] = i: 
v3 ^ v; 


- v2 >point.z) / 
v): 

- v2->point.z) / 
StvertexArray [i]); 


- v3->point.z) / 
v); 

v3 >point.z) / 
6fvertexArray[il); 


// (]lip new triangle recursively to preserve ontler. 

// New triangle ckxrsn’l need to be elip|X*tl agjiinst front plane ag;iin. 
ClipTriangle(&t, clipFlags & (clipFlagLeft | 
clipFlagRight | clipFlagTop | clipFlagBottom)): 


else if (b — 2) //Two vertices juv on the nc'gjitive side. 

{ // Find out which one is NOT 

if (!bl) 

1 

// GK)p origiiiiil triangle down to smaller triangle. 

12 = vertexCount >•; 

13 = vertexCount-H-; 

Vertex *v = SverLexArray[i2j: 

Vertex = &vertexArray[131: 
InterpolaLGVertices(v2, vl. (d v2 >point.z) / 
(vr>point.z - v2->point . 7 .), v); 
TnLerpolateVerticGs(v3. vl. (d - v3->point.z) / 
(vl->point.z - v3->poini.z). w): 
v2 = v; 
v3 = w: 


else if (!b2) 

I 

13 ~ vertexCount-H-; 

II ^ vertexCount-H-; 

Vertex *v ^ SvertexArray[13]: 

Vertex *w = &vertexArray[ilJ; 

InterpolateVert I.ccs(v3. v2. (d - v3->point .z) / 
(v2->po1nt.z v3->point.z), v): 

InterpolatcVertices(vl, v2. (d - vl >point.z) / 
(v2 >poirit.z - vl'>point.7.). w): 
v3 = v: 
vl = w; 

) 

else 

I 

11 = vertexCount++; 

12 = vertexCount-H-; 

Vertex *v = &vertexArray[il]; 

Vertex ‘w = &vertexArray[l2]; 
InterpolateVertice.s(vl. v3, (d - vl->point.z) / 
(v3->point.z - vl >poirit.z). v): 
InterpolateVert1 CCS (v2. v3. (d - v2->point.z) / 
(v3->point.z v2->point.z). v;); 
vl = v; 
v2 = w; 


) 
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else return; //All Uircc vertices on negative side — rejea triangle. 

) 

) 

if (clipFlags & clipFlagLeft) //(lip against left phinc. 

{ 

// Calaihie dot pnxliict of each vertex position with plane’s normal. 

float dl = vl->point.z + vl >point.x * d; 

float d2 “ v2->point.z + v2->point.x * d: 

float d3 ** v3->point.z + v3->point.x * d; 

long bl = (dl < O.OF); 

long b2 = (d2 < O.OF); 

long b3 - (d3 < O.OF); 

long b = bl + b2 + b3; 

if (b != 0) 

{ 

if (b = 1) 

{ 

if (bl) 

1 

11 vertexCount-H; 
long i *= vcrtcxCount-H-; 

Vertex *v = &verloxArrt3y[il] ; 

InterpolateVertices(vl, v2. dl / (dl d2), v); 

InterpolateVertices(vl. v3. dl / {dl d3). 

&vertexArray[ij); 
t.index[0l “ i; 
t.index[l] = il; 

(.index[2] =13: 
vl = v; 

1 

else if (b2) 

I 

12 “ vertexCount-H-; 
long i = vertexCount++; 

Vertex •v = &vertexArray[i2l; 
TiUcrpolateVertlr.e.‘5(v2, v3. d2 / (d2 - d3), v); 
InletpolaicVcriIces(v2. vl. d2 / (d2 - dl), 

StvertexArray [i]); 
t.index[0] = il; 
t.index llj = i; 
t.index[2l “ i2; 
v2 = v; 

) 

else 

I 

13 = vertexCouiiL-H-; 
long i = vertexCount++; 

Vertex *v &vertexArray Li3j; 
InterpolateVertices(v3, vl, d3 / (d3 - dl), v): 
TnterpolateVertices(v3, v2, d3 / (d3 - d2), 

&vertexArray[il); 

L. index [0] = i3; 
t.indexil] = 12: 
t.index[2] = i; 
v3 - v; 

) 

CllpTrlangle(&t, clipFlags & (clipFlagRight | 
clj pFlagTop I elipFlagBottora)); 

) 

else if (b = 2) 

1 

if (!bl) 

I 

12 = vertexCount++; 

13 = vertexCount1 I: 

Vcriex *v = &vertexArray[12]: 

Vertex ’w = &vcrLcxArtay[13] ; 

InterpolateVertices(v2. vl, d2 / (d2 dl), v): 

InterpolateVertices(v3. vl, d3 / (d3 dl), w): 

v2 “ v: 
v3 = w; 

1 

el.qe if (!b2) 

( 

i3 = veriexCouni-H-; 
il = vertexCount-H-; 

Vertex *v = &vertexArray[i3] : 

Vertex *w = &vertexArraylil]; 
InterpolateVertices(v3, v2, d3 / (d3 - d2), v); 

InterpolateVertices(vl, v2, dl / (dl - d2) , w): 

v3 = v: 
vJ = w: 

) 

else 


{ 

11 = vertexCountf+; 

12 = vertexCountl+: 

Vertex *v = &vertexArray[il] : 

Vertex *w = &verlcxArray[i2] : 
InterpolateVerticesCvl, v3, dl / (dl d3), v): 
InterpolateVertices(v2, v3, d2 / (d2 - d3). w): 
vl = v: 
v2 = w; 

I 

) 

else return: 

) 

1 

if (clipFlags & clipFlagRight) 

I 

float dl = vl->point.z * vl->point.x * d; 

float d2 = v2->polnt.z - v2->point.x * d; 

float d3 = v3 >point.z - v3->point.x * d: 

long bl - (dl < O.OF): 
long b2 = (d2 < O.OF); 
long b3 = (d3 < O.OF); 
long b = bl f b2 + b3: 
if (b != 0) 

( 

if (b = 1) 

( 

if (bl) 

{ 

11 = vertexCount++; 
long i = vertexCount-H-; 

Vertex *v = &vertexArray[il] ; 

interpolaLc.Vertir.en(vl , v2, dl / (dl - d2), v); 
InterpolateVerLiccsivl, v3. dl / (dI - d3K 
&vertexArray[i]): 
t.index[Oj = i: 
t.index[IJ = il; 
t.index[2l = i3 ; 
vl = v; 

) 

else if (b2) 

{ 

12 = vertexCount'H-; 
long i ^ vertexCount-H-; 

Vertex *v ^ &vertexArray[12] : 

InterpolateVertices(v2. v3. d2 / (d2 - d3), v): 
TnterpolateVertice.s(v2, vl. d2 / (d2 - dl), 

&verlcxArray[il): 
t.index[0] = i1 : 
t. index [l] = i: 
t.index[2j = i2: 
v2 = v: 

I 

el.se 

I 

13 = verlexdounr-H-: 
long i = vertcxCouni-H-: 

Vertex *v = SevertexArray [13] : 
InterpolateVertices(v3, vl. d3 / (d3 dl), v); 
InterpolateVertices(v3, v2, d3 / (d3 - d2), 

StvertexArray [i]) ; 
t..i.ndex[0] = i3; 

L.lndex[l] = 12: 
t.index[2] ” i: 
v3 = v; 

1 

ClipTriangle(&t, clipFlags 6e (clipFlagTop | 
clipFlagBottom)); 

) 

else if (b = 2) 

I 

if (!bl) 

I 

12 = vertexCount-H-; 

13 = vertexCount-H-; 

Vertex *v = &vertexArray[i2]: 

Vertex *w = &vertexArray[i3l; 

InterpolateVertices(v2, vl, d2 / (d2 - dl), v); 
interpolatoVcrtice.s(v3, vl, d3 / (d3 - dl), w); 
v2 = v; 
v3 = w: 

] 
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else if (!b2) 

I 

i3 ” vertoxCounfH-; 
il = verLexCount++; 

Vertex 'v = fitvertexArrayLi3j; 

Vertex *w = &vertexArray[il] ; 
InterpolateVertices(v3, v2. d3 / (d3 - d2), v); 

InterpolateVertices(vl, v2. dl / (dl - d2). w): 

v3 = v; 
vl = w; 

I 

else 

I 

11 = vertexCount-H-; 

12 ^ vertexCount-H-; 

Vertex *v = &vertexArray[il]; 

Vertex *w = &vertexArray[i2]; 
InterpolateVertices(vl, v3, dl / (dl - d3) , v) ; 

TnterpolateVerticcs(v2, v3, d2 / (d2 d3), w) ; 

vl * v; 
v2 = w; 

1 

I 

else return: 

I 

) 

if (clipFlags & clipFlagTop) 

float dl = vl->point.z * h + vl->point.y * d: 

float d2 = v2->point.z * h + v2->point.y * d; 

float d3 * v3*>point.z * h + v3->point.y * d; 

long bl = (dl < O.OF): 
long b2 = (d2 < O.OF); 
long b3 » (d3 < O.OF); 
long b = bl + b2 + b3; 
if (b != 0) 

1 

if (b 1) 

{ 

if (bl) 

( 

11 = verLexCounfH-; 
long i = vertexCount-H-; 

Vertex *v = &vertexArray[il] : 
InterpolateVertices(vl, v2, dl / (dl - d2). v); 
InterpolateVertice.s(vl, v3, dl / (dl - d3), 

fivertexArray [i]): 
t.index [0] = i: 

L.index[1] = il: 
t.index[2J = i3: 
vl = v; 

I 

else if (b2) 

I 

12 = vertexCount-H-; 
long i = vertexCount-H-; 

Vertex 'v = &vertexArray[i2j: 
lnterpolateVertices(v2. v3, d2 / (d2 - d3), v); 
InterpolateVertices(v2. vl. d2 / (d2 - dl). 

&vertexArrayLi]): 
t.index[0] “ il; 
t. index [1] = i; 
t. index [2] =* i2; 
v2 v; 

) 

else 

1 

13 * vertexCount-H-; 
long i = vertexCountH; 

Vertex *v = &vertexArray[i3] ; 
TnterpolateVertlccs(v3. vl. d3 / (d3 dl). v); 
TntcrpolatcVerLlces(v3. v2. d3 / (d3 * d2). 

6iverlexArray [i]); 
t.index[Oj = i3: 
t.index[Ij = i2; 
t.index[2] = i; 
v3 = v; 

) 

ClipTriangle(&L. clipFlags & clipFlagBottom); 
else if (b = 2) 


( 

if (!bl) 

{ 

12 = vertexCount H ; 

13 = vertexCount-H-; 

Vertex *v * iveriexArray[i2]; 

Vertex 'w = &vertexArray[i3]; 
lnterpolateVertices(v2. vl, d2 / (d2 - dl). v); 
InterpolateVertices(v3. vl, d3 / (d3 - dlK w); 
v2 = v; 
v3 = w; 

) 

else if (!b2) 

I 

13 = verlexCounL-H-; 
il = vertexCount+t; 

Vertex *v = &vertexArrayli3j: 

Vertex *w = &vertexArray[il]; 
InterpolateVertices(v3. v2, d3 / (d3 - d2), v); 

InterpolateVertices(vl. v2, dl / (dl - d2), w); 

v3 = v; 
vl = w: 

) 

else 

I 

11 = vertexCount-H-; 

12 = vertexCount++; 

Vertex *v = &vertexArray[il]; 

Vertex *w = ^tvertexArray [12] ; 
TnterpolatoVertices(vl. v3. dl / (dl d3). v); 

TntcrpolatGVerticos(v2. v3, d2 / (d2 d3), w); 

vl = v; 
v2 = w; 

I 

) 

else return; 

) 

1 

if (clipFlags & clipFlagBottom) 

I 

float dl “ vl->point.z * h - vl->point.y * d; 

float d2 = v2->point.z * b - v2->point.y * d; 

float d3 = v3->po1nt.z * h v3 >point.y * d; 

long bl = (dl < O.OF); 
long b2 = (d2 < O.OF); 
long b3 = (d3 < O.OF); 
long b = bl + b2 b3; 
if (b != 0) 

I 

if (b = 1) 

I 

if (bl) 

I 

11 = vertexCount++; 
long i = vertexCount-H-; 

InterpolateVerticGs(vl, v2, dl / (dl - d2), 
&vertexArray[ill); 

InterpolateVGrtices(vl, v3, dl / (dl - d3), 
&vertexArray[i]); 
t.index[0] ^ 1; 
t.index[1] = il; 
t.index[2] = i3: 

I 

else if (b2) 

{ 

12 = vertexCountI I; 
long i = vertexCoiint-H-; 

IntcrpolatcVortlccs(v2. v3. d2 / (d2 d3). 

&vertexArray[i2]); 

InterpolateVertices(v2, vl, d2 / (d2 - dl), 
fievertexArray[ij); 
t.index[0] - il; 
t.index[1] = i; 
t.index[2] = i2; 

) 

else 

( 

13 = vertexCount-H-; 
long i - vertexCount-H-; 

InterpolateVerticGs(v3, vl, d3 / (d3 - dl), 

&vertexArray[i3l); 

TnterpolateVertices(v3. v2, d3 / (d3 - d2) . 
&vcrtoxArray[i]); 
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t. indexfOl = i3; 
t.index= i2: 
r, index [P.j = i; 


CiipTriangle(&t. clipFlagNone); 

1 

else if (b ^ 2) 

I 

if (!bl) 

I 

12 - vcr toxCoijnt-l-+; 

13 = verLoxCounl++; 

InterpolateVertices(v2. vl, 62 / (d2 - dl), 
&vertexArray(i2]): 

InterpoiateVertices(v3, vl, d3 / (d3 - dl), 
&vertGxArrayLi3j); 

) 

else If (Ib2) 

( 

i3 = ver LexCount-H-; 
il = vertexCouriL-H-; 

InterpoiateVertices(v3, v2, d3 / (d3 - d2), 
&vertexArray[i3]); 

InterpolateVertices(vl. v2, dl / (dl d2), 
fiivertexArraylilj); 

I 

else 


11 = verlexCount-H*; 

12 = vertexCouriL-H-; 

InterpolateVertices(vl. v3. dl / (dl - d3), 
&vGrtexArray[ilJ): 

InterpolateVertices(v2. v3, d2 / (d2 - d3), 
fitvert.exArray [121): 


else return: 


] 

//Add clipixxl triangle to the triangle array. 

Tricing!0. *newTriangle = &triangleArray[triangleCounfH-J : 
iiewTrlanglG->index [0] = il; 
newTriangle >indcx(l] ^ 12; 
newTriangle->index(2] = i3; 

} 


Visibility Determination 

Visibility determination is the mcc:hanisni by wliich an engine 
figures oui early in die ivndcring process what pails of a scene are 
ptxcntially visible for a given camera configuration. Determining ilie 
potetitially visihhset abbreviated PVS) of ol)jccLs usually 

involves algorithms which arc very sjx'cific to a particular engine, 
and the prexess often appeal's to be more of an art than a science. 
Tlie highest level of visibility determination is hc^avily dependent on 
tlie type of environment an engine lias to deal witli. The methods 
that an engine would use to determine what interior walls of a castle 
are visible are completely different from the methcxls that would be 
used to determine the visibility of large objecis in outer space. 
Discaissing the complex systems in use by texlay’s state-of-the-art 
engines to detennine the visibility of large staictures in a large 
environment Is Ixfyond the sc'ope of this article. This scxiion 
descTibes the lower levels of visibility detennination and provides a 
meiluxl for quickly dc*tennining whether all or part of an object 
might intersect the view frustum (thus making it potentially visible). 

We have already visited the lowest level c^f visibility 
determination in llie f)revious section. Triangle-level visibility is 
handled in part by the clipping algorithm, which is able to 
determine whether a triangle is completely visible, partially visible, 


or not visil)le at all. Before a triangle is clipi^ed, however, we should 
chexk to see whetlier it Is actually facing the c^iimera. As long as 
solid mcxlels are l:>eing used, any triangle which is facing away from 
the c'cimera will lx* completely olxscured by some other part of the 
nuxlel. The prexess of removing these triangles from the rendering 
pipeline is allied backface culling. We c an (juic:kly detennine that 
a triangle is facing away from die camera by calcLilating the dot 
[ircxluct Ixtwcen the triangle’s nomial vector and the direction to 
the camem. If die dot product is ptxsitive, dien the triangle is facing 
the camera; otherwise, it should lx culled. Tlie direction to the 
camera for a fiarticular triangle can be obtained by subtracting any 
one of the triangle’s three vertices from the camera position. 
However, the vertex positions are represented in a model’s local 
coordinate space and the camera jxisition Is represented in world 
space. Before ixrforming any backface culling calcailations for a 
particular mcKlel, we need to iransfonn the global camera jxisition 
into the iikxIcTs object space. This Is easily accomplished by 
multiplying the camem position by the inverse of the itkxIcTs object 
to world transformation matrix as demonstrated in die RenderMesh 
function shown in Listing 6. 

At the next higher level al'xve individual triangle's, we need to 
lx able to determine the visibility of entire mcxlels such as characters 
and projectile's. Mcxlel-level visibility is the primary topic of this 
section and will lx accomplished through the use of hounding 
mlumes. Bounding volumes are shapes which have a simple 
geometry and completely encompass the mcxlels to which they 
corresixxid. The simplest geonietiy that can Ix^ used for a moders 
bounding volume Is a sphere, 'file c^asic?si way to obtain a decent 
bounding sphere for a triangle mesh is to calculate the average of 
the mesh’s vertex ccxidinates to seive as the center and the 
maximum distance from any vertex to the c enter to serve as die 
radius. For nicest meshes it is fxissible to construct a lx>utiding 
volume suc:h as an ellipsoid or a Ixix which contaias less empty 
sfiace around a nicxlel than a sphem dexs, but such a volume would 
rexjuire considerably more expensive visibility eralculations. We 
therefore restrict our discussion to Ixxmding spheres in the interests 
of sim|)licity and efficiency. 

liefore we spend valuable prexessor time transfonning a 
mesh’s vertices into c:amera space and clipping its triangles to the 
view faistum, we want to make sure that the mesh’s bounding 
sphere actually falls at least partially within the c:amera's field of 
view. We apply this test by meastiring the distance from the 
bounding sphere’s center to each of the view faistum’s planes in 
world space. If the sphere’s center falls on the side of any 

plane by a distance greater than or cxjual to its radius, dien no part 
of the mcxlel suiTounded by die sjihere is visible and thus should 
not lx rendered. If die sphere’s center falls on the lx)sitiw side of a 
plane by a distance gre^iter tlian or ecjual to its radius, then we know 
that no vertex in the mesh falls on die negative side of die plane. 
This infonnation enables us to make an optimization later by 
excluding that plane when the mesh’s triangles are c:lipped. The only- 
bits in the dipFlags parameter whic:h is pa.ssed to die ClipTiiangle 
fimetion that ncxd to lx set arc diose diat conespond to planes for 
which the distance from the plane to the Ixxmding sphere’s center 
is less than the sphere’s radiits. 
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In order to perform ihe bounding sphere calculations in 
world space, we need to know the world sj)ace normal 
vectors for each of the view frustum planes. The normal 
vector for the front plane is simply the camera’s viewing 
direction. The normal vectors for the four side planes are 
calculated in the PrepareToRender function shown in Listing 
2. The actual bounding sphere visibility te.st is implemented 
in the SphereVisible function shown in Listing 5. This 
function returns a boolean value indicating whether the 
sphere is at least partially visible, and if so, also returns a set 
of flags indicating which planes have to be checked during 
the clipping process. 

Listing 5: Bounding sphere visibility test 

Sphere Visible 

This ftinction retiiras a booknin v;iliic indicating whctlicr a mesh’s bounding sphere is 
visible. If true, then the clipFlags parameter is set to indicate which phmes the 
sphcTt* inicrstx'ts and thus need to be considered for clipping. 

bool MyEngine::SphereVisible(const Vector3D& worldCenler, 
float radius, long *clipF]ags) 

1 

long flags = clIpKlagNone: 

float f * vicwPlaneDistance * maxDepth; 

VeclorSD cameraRelativeCenter = 
worldCenter - cameraPosition; 
float d - cameraRelativeCenter * viewDirecti on; 
if (d < f * radius) return (false); 
if (d < f 1 radius) flags |= clipFlagfront; 
d = cameraRelativeCenter ‘ leftPlaneNormal; 
if (d < -radius) return (false); 
if (d < radius) flags |= ciipFlagLeft; 
d = cameraRelativeCenter * rightPlaneNormal; 
if (d < -radius) return (false): 
if (d < radius) flags |= clipFlagRigbt; 
d = cameraRelativeCenter * LopPlaneNonnal; 
if (d < -radius) return (false); 
if (d < radius) flags |= clipFlagTop: 
d " cameraRelativeCenter * bottomPlaneNonnal; 
if (d < -radius) return (false); 
if (d < radius) flags |= clipFlagBottoni; 

*clipFlags “ flags; 
return (true); 

1 

Summary 

Tliis article has covered several fundamental topics with 
which every 3f> engine designer needs to lx: familiar. We now 
have all of llie mathematical tools which are necessary to render 
an arbitraiy triangle mesh on the screen. These tools are 
combined in the RenderMesh function shown in Listing 6. This 
function takes a mesh and first determines whether is it visible by 
calling the SphereVisible function. If it is visible, then the mesh’s 
vertices are transformed into camera space with the 
TransformVertices function. Finally, backface culling and clipping 
are |X’rformed one triangle at a time. 

This is as far as we can go and still maintain platform- 
independence. 'fhe only remaining step is to transform the 
vertices into screen space (by applying equations (14) and (15)) 
and send them to the 3D acceleration API. We could gain some 
efficiency by changing the vertexArray and triangleArray members 
of the MyEngine cla.ss to be arrays of the native vertex and 
triangle structures of the API being used (for instance, 
TQAVTexture and TQAIndexedTrlangle under QuickDraw 3D 


ItAVE). If this is done, then the TransformVertices function would 
have to be modified to store the camera space vertices in the 
API’s native format, and the InterpolateVertices tlinction would 
have to be modified to work with lliis format as well. 

'there are, of c'oui'se, many additional conifxmcnLs to every 3D 
engine that this article has not explored such as lighting, animation, 
and collision detection, whose design depends more heavily on an 
engine’s ultimate applic'^Uion than die material [ircscnicd herein. The 
goal has been to provide a gcxxl .starting point for those who wish 
to create their own 3D universe and lo provide a strong foundation 
on which to build these higher-level systems. 

Listing 6: Rendering a mesh 


RenderMesh 

This function does everything which is necessary to render a mesh.The 
PrepareToRender function should be called before any RenderMesh 
calls are made. 

void MyEngine::RenderMesh(c.on.st Mesh *raesh) 

( 

long clipFlags: 

// First check if bounding splKrc is visiWe. 
if (SphereVisible(mesh->objectToWorldTransfonn * 

mesh->boundingSphereCenter, mesh->boundingSphereRadius. 
&clipFlags)) 

{ 

const Vertex ‘vertex = mesh >vcrlcxArray; 
con.st Triangle ‘triangle = mesh >triangieArray; 

//Transform vertices into camera s|)acc. 

TransformVertices(m€sh->vertexCount, vertex, 
mesh->objectToWorldTransform); 

// Calculate c'amcra position in object s|race. 

VectorSD localCameraPosition = 

Inverse (mesh->objectToWorldTransforin) * 
cameraPosition; 

// I^rform backlace culling and clipping for each iiiangle. 

LriangleCount = 0: 

for (long a = 0; a (■ mesh->triangleCount; all) 
f 

const Vertex *v = &vertexftriangle->index[0] ] : 
float d = (localCameraPosition v >point) ‘ 
triangle->normal; 

if (d > O.OF) ClipTriangle(triangle, clipFlags); 

L riarigle-H-; 

1 

if (triangleCount != 0) 

I 

//At this point we can transform the vertices into screen space using 
// equations (14) and (15), and then submit tht*ni to the 3D acceleration API 
// for rendering. 

) 

) 

1 
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TIPS 8k 
TIDBITS 


by Jeff elites <online@mactech,com> 


rX)NVERSI()N FROM lYTRl. ByTE ORDER 
Intel niicix)prcx:css()rs store integer cliiia in a different way than the 
PowerPC d(K^. 'llie Powerl^ (oiXM'ating under tlie Mac OS) stores the bytes 
in big endian order, from the most significant to the least significant, while the 
Intel pr(K-e.ssor uses the opposite byte order (little endian). 

When you are using a Macintosh but have to read a file created on a 
computer with an Intel prexessor, or when you have to write a file for later 
use on an Intel machine, tiiis difference is something you have to worry 
alx)ut. You can use the following routines to convert shorts and longs bac’k 
and forth Ixtween the two byte orders. 

^define MotoroiaToIntelLong IntelToMotorolaLong 
^define MotorolaToIntelShort IntelToMotorolaShort 
r PruioCypcs 7 

unsigned long IntelToMotorolaT.ong (unsigned long original); 
unsigned short IntelToMoiorolaSliori 

(unsigned short original); 

t Inid 10 M()ion)l;i bytes order V 
r little endian to big aidcin V 

unsigned long IntelToMotorolaLong (unsigned long original) 

{ 

unsigned long converted; 
char *b; 
converted = OL; 

if (original — 0) return converted; 
b ” (char*)&converted; 

*b-H- = (char) (original); 

*b-H- = (char) (original » 8); 

*b++ - (char)(original » 16); 

*b++= (char) (original » ?.4); 
return converted; 

1 

r Intel to .MototxAi bytes order V 
r little endian to big endian 7 
unsigned short IntelToMotorolaShort 

(unsigned short original) 

I 

unsigned short converted; 
char *b; 
converted = 0; 

if (original = 0) return converted; 
b = (char *)&converted; 

*b-H- = (char) (original); 

*b++ = (char)(original » 8); 
return converted; 

} 

Marco Bambini 
<m.arco@spicle}iink it> 

C++ Fdue Streams and FSSpecs 

When using ANSI C and C++ file routines, Macintash programmers am 
into die unfoaunate snag that diese routines assume that files are properly 
identified by pitih names, but under the Mac OS dicy arc specified tlmnigh 
an FSSfxe data stnictiire. Of course, it is possible to obtain the full path to a 
file given its FSSjxc, but iliis isn’t rcally a .solution, because on the Macintosh 
hill path names cbn't uniquely identify files (for iasiance, if die u.ser has more 
dian one mounted disk with die same name). 

Fortunately, Meirowerks has provided FSp.fopen, w+iich works like 
C’s fopen except that it uses FSSjxes iastcad of paths. To similarly obtain a 
C++ file stream you have to do a little more work, but the following example 
from Meirowerks’ MWRon <MWRon@metrouKni^wm>Qkimns{n^^^^ how to 
do it with minimal fuss. 


//include <ioslream> 

//include <fstream) 

//include <SI0UX.h> 

//include <unistd.h> 

//include <cstring> 
using namespace std; 

int GetStreain(FSSpcc ^fs. ifsLream Siin); 
void Tnit ial i?>c(void); 
const ini PSIZK = 256; 
char AppPatiiName [PSIZEj: 
char FilePathNamefPSIZE]; 
int tnainO 
( 

// initialize your managers 
Initial izeO; 

SlOUXSctIIngs.initializeTB = FALSE; 

i f s I ream in; // input file 

strcpy(AppPathName . “”); //jiifety 

strcpy(FilePathName , ""); //.s;ifet>' 

const short kNilFilterProc = nil;//use dialog to open file 

StandardFileReply reply; 

short numTypes = 0; 

SFTypel.ist typcLisl; 

FSSpcc fs; 

SLandardGetFile( kNilFiiterProc, numTypes, typeList, &reply); 
fs = reply.sfFiie; 

if(GetStream(fs. in)) exit(l); //stfcani foiled to open 
strcat(FilePathName. p2cstr(fs.naine) ); 
c2pstr((char *)fs.naine); 

// .see where we are at now 

cont « “The folder holding the executable is \n’' 

<< gGtcwd{AppPathName, PSIZE) « endl; 
cout « “The opened file’s full name is \n" 

« FilePathName << endl; 

return 0; 

1 

ini GciSlrcam(FSSpec &fs. ifstream &in) 

I 

short savedVoi; 

OSErr err - 0; 

//get volume of application 

if ( (err = GetVoKO, &savcdVol)) != NULL) 
return err; 

// set working volunK 

if ((err = HSetVoKO, fs.vRefNum, fs.parlD)) != NllU,) 
return err: 

// open file 

in.open(p2cstr(fs.namc)); 
lf(!in) ( err = 1; return err;) 
c2psLr((char *)fs.naine); 

getewd (FilePathName. PSIZE); // gel working directory 

// reset voliune of application 
if( (err - SetVoKO, savedVol)) != NULL) 
return err; 

return err: 

) 

void Initialize(void) 

( 

/* Initialize all the needed managers. 7 
InitGraf(&qd.thePort); 

InitFontsO; 

InitWindowsO; 

TnliMcnusO; 

TEInilO; 
initDialogs(nil): 

InitCursorO; 
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It'l simply amazing. In a very short time, vast new horizons 
have opened up in the Mac market. Anything—and everything— 
is now possible! Discover the most exciting new possibilities at 
MACWORLD Expo/New York ’99I 

See and demo all the hot new products from hundreds of industry-leading 
vendors. Stay on top of new developments that could impact your buying decisions. 
Take advantage of money-saving specials when you buy products right on the show 
floor! Network with industry experts and make deals with other professionals. 
MACWORLD Expo is the best place to learn about the hottest solutions for: 

• education and development 

• advertising and graphic design 

• printing and publishing 

• home computing 

• digital content creation, management and delivery 

• the Internet 

• software development 

• new media 
« gaming 
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or cafi Soo-^ltSrEXPd 


Sponsored by: 

miaciioriii 

Macwraxmi 

Managed by: 

m \DG 


Yes! Please send me more information on 
MACWORLD Expo/New York! I'm interested in: 
(3 Attending Exhibiting 




Name. 


Title. 


Company_ 

Address_ 

City/State/Zip, 

Phone_ 

Email_ 


Fax 


(if you would like to receive information via email about MACWORLD Expo) 

Mail to: MACWORLD Expo. 1400 Providence Highway, 

PO Box 9127. Norwood, MA 02062. Or Fax to: 781.440.0357 

THIS IS NOT A REGISTRATION FORM. 




































Whoa. New technology. 
I need updated tools. 



CodeWarrior solves problems. We’re continually updating our award-winning 
Mac-hosted development suite so your applications can take advantage of the 
latest technologies from Apple. Thinking about Mac OS X, Carbon or AltiVec? 

So is Metrowerks- CodeWarrior - still fast, powerful, easyto use. 

No problem with that, right? 


PROBLEM SOLVED. CODEWARRIOR. 

1 . 800 . 377.5416 

For more information on CodeWarrior's support for new Apple technology, check out: 


www.metrowerks.com/newtech 



metrowerks 
















